v0.0.1alphaHEADmain

1 files changed, 143 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..ff75b883
--- /dev/null
+++ b/README.md
@@ -0,0 +1,143 @@
+# Reactance - User Manual
+Censorship resistant scalable VPN/Proxy automation for OpenBSD with user management for servers and cloud services.
+
+Supported OpenBSD versions: 7.4 (Tested)
+
+## Table of Contents
+  - [Description](#description)
+  - [Protocols](#protocols)
+  - [Server Definitions](#server-definitions)
+  - [User Definitions](#user-definitions)
+  - [Playbook Execution](#playbook-execution)
+  - [Client Website](#client-website)
+  - [Reading Logs](#reading-logs)
+  - [CI/CD Pipelines](#cicd-pipelines)
+  - [Contributing](#contributing)
+
+## Description
+Reactance is a complete automation to handle installation, user management, credential distribution of censorship-resistant VPN protocols on your openbsd server/cloud service(s) of choice. The server configuration is done through setting inventory variables. User configuration is done through using host and group variables. Read [Server Definitions](#server-definitions) and [User Definitions](#user-definitions) for more info.
+
+Reactance builds websites for users/clients to view documentations and credentials. The htpasswd credential and URL of the website is showed at the end of `web` role at the end of reactance run.
+
+It is also possible to test and deploy the VPN automation through using CI/CD pipelines. Please read [CI/CD Pipelines](#cicd-pipelines) for more info.
+
+The goals of this project are:
+- Automatically setting up a wide range of up-to-date secure VPN services  on OpenBSD
+- Automated User Management and Expiration
+- Bypassing Censorship
+- Easy to set up and manage
+
+## Protocols
+These are the protocols currently supported by Reactance. Protocols upper in the list are more preferable for usage because of security and performance.
+
+**NOTE: Hysteria2 is disabled by default. Because the sing-box clients available on the different platforms do not have any mechanism for verifying the proxy server's identity thus there's possibility of MITM attacks. Even if you include Hysteria users and settings in your configuration files, it would be ignored**
+
+|Protocol|Service|Authentication Method|Server Verification Method|Auto DNS Proxying|
+|--|--|--|--|--|
+|Cisco AnyConnect|OpenConnect|Certificate|TBD|Yes|
+|Trojan|Xray core|Password only|XTLS Vision|Yes|
+|VLESS|Xray core|UUID|XTLS Vision|Yes|
+|VMESS|Xray core|UUID|XTLS Vision|Yes|
+|SOCKS|SSH|private key|matching keypairs|No|
+|Hysteria v2|Hysteria v2|Username & Password, Obfuscation|TBD|No|
+
+## Server Definitions
+Servers are defined in inventory.yaml file. There are different groups for different services.
+Supported groups: `all_vpns`, `vless`, `vmess`, `trojan`, `sshvpn`, `hysteria`, `ocserv`
+
+Example: The following config will setup all vpn servers on box1, only ocserv on box2 and box3
+
+```json
+all_vpns:
+    hosts:
+        box1:
+            host: deez.example.com
+
+ocserv:
+    hosts:
+        box2:
+            host: nuts.example.com
+            user: user2
+            ocserv_network: "10.20.30.40/24"
+```
+   
+All variables:
+|Name|Description|Default Value|Used Under|
+|--|--|--|--|
+|host|server hostname|(None)|all|
+|port|server ssh port|22|all|
+|private_key_file|path to ssh private key file|.ssh_private_key (required for DroneCI)|all|
+|ocserv_network|network address for ocserv|172.16.16.1/24|all_vpns, ocserv|
+|ocserv_port|port number for openconnect server|4430|all_vpns, ocserv|
+|hysteria_port|port number for hysteria|4435|all_vpns, hysteria|
+|trojan_port|port number for trojan|4436|all_vpns, xray|
+|vless_port|port number for vless|4437|all_vpns, xray|
+|vmess_port|port number for vmess|4438|all_vpns, xray|
+|disable_dns|disable dns and adblock setup|false|all|
+|root_keys|root user ssh public keys|None|all|
+
+## User Definitions
+Users can be set up based on protocol (same users across all servers for same services) or hosts (specific users on specific servers). For user management based on services, write your user definitions in `group_vars/all.yaml`. For user management based on specific hosts, write your user definitions in `host_vars/all.yaml` (group_vars would be overriden for that host).
+
+The parameters for the user definitions are:
+|Parameter Name|Description|Type|Default Value|Importance|
+|--|--|--|--|--|
+|user|username|string|None|required|
+|regen|overwrite existing password|boolean|false|optional|
+|expire|user expiration date (format: yyyy-mm-dd)|string|None|optional|
+
+Supported user lists are: `all_users`, `sshvpn_users`, `vless_users`, `vmess_users`, `trojan_users`, `hysteria_users`, `ocserv_users`
+
+### Configuration Example
+```yaml
+# users set in all_users would be set up for every service
+all_users:
+    - user: foo
+    - user: bar
+vless_users:
+    - user: baz
+      regen: true # will regenerate password
+      expire: 2025-10-13 # will remove user after yyyy-mm-dd
+```
+
+## Playbook Execution
+
+Step 1: It's recommended to run the playbook through a DroneCI pipeline. However if you wish to run it locally from your computer, run the following commands:
+```sh
+apt install rsync # or whatever your package manager is
+python3 -m venv .venv
+source .venv/bin/activate
+pip3 install ansible netaddr
+git submodule add -f https://github.com/alex-shpak/hugo-book web/themes/hugo-book
+```
+
+Step 2: Reactance is ran as the root user. Please copy a public key to your server's `/root/.ssh/authorized_keys` file. Copy the private key and store it on DroneCI under the secret `ssh_private_key`. Or, if you're running reactance manually, store the private key file path under the `private_key_file` parameter in inventory.yaml.
+
+Step 3: To execute the playbook, you can run a manual pipeline build on DroneCI from the Web UI. If you want to execute the playbook manually, simply run:
+```sh
+ansible-playbook reactance.yaml
+```
+
+## Client Website
+The clients can retrieve the VPN credentials and read the docs from the client site that they can access from `http://x.x.x.x/client_name/index.html`. htpasswd based authentication is for authenticating the clients on the sites. The htpasswd credentials along with the URLs are shown at the end of reactance run (web role) or at the end of `setup_web` task in DroneCI.
+The VPN credentials can be retrieved and the docs can be read from the client website. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) to know how to update the site.
+
+## Reading Logs
+How to debug and fix errors with VPN services
+1. Reading logs
+
+|Protocol|Log File|
+|--|--|
+|ocserv|/var/reactance/ocserv/ocserv.log|
+|hysteria|/var/reactance/hysteria/hysteria.log|
+|xray|/var/reactance/xray/logs/{xray_access.log, xray_error.log}|
+|sshvpn|/var/log/authlog|
+
+2. Reading system calls: You can use `ktrace` and `kdump` to read system calls of processes to see if any errors appear.
+
+## CI/CD pipeline
+You can test and deploy vpn services on your server using CI/CD pipelines. As of now, only DroneCI is supported because of its simplicity, flexibility and ease of use. A `utils` folder can be found that contains a Dockerfile and drone starlark configuration for running the drone pipeline. Starlark is used instead of YAML, to make it easier to add/remove services.
+You need to set the drone config path to `utils/drone.star` in the webui and also store the ssh key as a drone secret in `ssh_private_key` variable.
+
+## Contributing
+To contribute to the project, please refer to [CONTRIBUTING.md](./CONTRIBUTING.md)