From 372a049fff8df430fe97a0f16f4638808d120f7b Mon Sep 17 00:00:00 2001 From: anhcq151 Date: Sun, 8 Aug 2021 22:23:03 +0700 Subject: [PATCH 1/6] build documentation page --- .github/workflows/build-release-doc-pages.yml | 32 +++ docs/SETUP.adoc | 186 ++++++++++++++ docs/cli/ansible/README.adoc | 201 +++++++++++++++ docs/cli/python/DEV.adoc | 224 +++++++++++++++++ docs/cli/python/OVERVIEW.adoc | 79 ++++++ docs/cli/python/src/client/VPNC_README.adoc | 233 ++++++++++++++++++ docs/cli/python/src/command/README.adoc | 124 ++++++++++ docs/index.adoc | 113 +++++++++ 8 files changed, 1192 insertions(+) create mode 100644 .github/workflows/build-release-doc-pages.yml create mode 100644 docs/SETUP.adoc create mode 100644 docs/cli/ansible/README.adoc create mode 100644 docs/cli/python/DEV.adoc create mode 100644 docs/cli/python/OVERVIEW.adoc create mode 100644 docs/cli/python/src/client/VPNC_README.adoc create mode 100644 docs/cli/python/src/command/README.adoc create mode 100644 docs/index.adoc diff --git a/.github/workflows/build-release-doc-pages.yml b/.github/workflows/build-release-doc-pages.yml new file mode 100644 index 0000000..ee91be5 --- /dev/null +++ b/.github/workflows/build-release-doc-pages.yml @@ -0,0 +1,32 @@ +name: Generate github pages + +on: + push: + branches: [ documentation-pages, main ] + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v2 + with: + ref: documentation-pages + + - name: Install asciidoctor + run: sudo apt-get install -y asciidoctor + + - name: Convert asciidoc files to html + run: | + find docs/ -name *.adoc -exec asciidoctor -a toc -a icons=font {} \; + find docs/ -name *.adoc -exec rm -f {} \; + + - name: Deploy to GitHub Pages + if: success() + uses: crazy-max/ghaction-github-pages@v2 + with: + target_branch: doc-pages-uat + build_dir: docs + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/docs/SETUP.adoc b/docs/SETUP.adoc new file mode 100644 index 0000000..4a25a57 --- /dev/null +++ b/docs/SETUP.adoc @@ -0,0 +1,186 @@ += Setup Development Environment + +* link:https://github.com/play-iot/iot-vpn/tree/main/scripts[scripts] folder contains some linux script to build/run `vpnserver`/`vpnc`/`vpnddns` and shared artifact to `vagrant` +* link:https://github.com/play-iot/iot-vpn/tree/main/docker[docker] folder contains a list of `vpnserver`/`vpnc`/`vpnddns` `dockerfile` and `docker-compose` + +== Vagrant + +It is used for test VPN client CLI in the specific environment/`OS`. + +Use link:https://github.com/play-iot/iot-vpn/blob/main/scripts/vagrant.sh[vagrant.sh] to `up`/`halt`/`destroy`/`status`/`port`/`ssh` one or multiple `vagrant` boxes. +The `vagrant` box parameter is one of folder name in link:https://github.com/play-iot/iot-vpn/blob/main/vagrant[vagrant] + +For example: + +[,bash] +---- +# Up multiple boxes +./scripts/vagrant.sh up ubuntu20 fedora32 debian10 +# ssh to one box +./scripts/vagrant.sh ssh ubuntu20 +---- + +== Docker multi arches + +* Use `docker` https://github.com/docker/buildx/#installing[buildx] +* Use `docker` https://github.com/zero88/gh-registry[registry] to distribute image in local registry + +[,bash] +---- +# Create buildx instance +$ docker buildx create --append --use --name multiarch --buildkitd-flags '--allow-insecure-entitlement security.insecure --allow-insecure-entitlement network.host' +$ docker buildx inspect --bootstrap +$ docker buildx ls + +NAME/NODE DRIVER/ENDPOINT STATUS PLATFORMS +multiarch * docker-container + multiarch0 unix:///var/run/docker.sock running linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6 +default docker + default default running linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6 + +# Create docker registry as service +$ docker run -v docker-registry-data:/var/lib/registry -p 5000:5000 --privileged --network host -d --restart always zero88/gh-registry:latest +---- + +== VPN server + +=== Docker + +link:https://github.com/play-iot/iot-vpn/blob/main/docker/dockerfile[Dockerfile] + +==== Build + +2 edition repositories: + +* `RTM` repository(`rtm`): https://github.com/SoftEtherVPN/SoftEtherVPN_Stable +* `Developer` repository(`src`): https://github.com/SoftEtherVPN/SoftEtherVPN + +2 based Docker images: `debian-slim`, `alpine` + +[,bash] +---- +# Build on slim and latest RTM version +./scripts/docker.vpnserver.sh build + +# Build on slim and specific RTM version +./scripts/docker.vpnserver.sh build slim rtm v4.34-9745-beta + +# Build on slim and src latest version +./scripts/docker.vpnserver.sh build slim src + +# Build on slim and specific src version +./scripts/docker.vpnserver.sh build slim src 5.01.9674 +---- + +==== Run + +[,bash] +---- +# Up on slim and latest RTM version +./scripts/docker.vpnserver.sh up + +# Up on slim and specific RTM version +./scripts/docker.vpnserver.sh up slim rtm v4.34-9745-beta + +# Up on slim and src latest version +./scripts/docker.vpnserver.sh up slim src + +# Up on slim and specific src version +./scripts/docker.vpnserver.sh up slim src 5.01.9674 +---- + +=== Use JSON-RPC + +[,bash] +---- +curl -k -X POST -H 'Content-Type: application/json' \ + -H 'X-VPNADMIN-PASSWORD: 123' \ + -d '{"jsonrpc":"2.0","id":"rpc_call_id","method":"Test","params":{"IntValue_u32":0}}' \ + https://localhost:8443/api/ +---- + +== VPN CLI + +=== Setup python environment + +[,bash] +---- +## Install pipenv +# By pip/or pip3 +pip3 install pipenv +# Debian Buster+: +sudo apt install pipenv +# Fedora/Redhat/centos +sudo dnf install pipenv + +# In root project dir +pipenv install +# Join pipenv in virtualenv +pipenv shell +---- + +=== VPN client + +==== Build and test + +link:https://github.com/play-iot/iot-vpn/blob/main/cli/python/docker/vpnc.Dockerfile[vpnc.Dockerfile] + +[,bash] +---- +#========================================================== +#### USE VAGRANT ------------------------------------------ +# Build VPN Client CLI then copy to vagrant/shared +$ ./scripts/build.vpnc_2_vagrant.sh +# go to any box in vagrant folder then up. Binary file will be synced to /vagrant/playio-vpnc +# with ubuntu20 +$ ./scripts/vagrant.sh up ubuntu20 && ./scripts/vagrant.sh ssh ubuntu20 +# now, it is inside vagrant guest machine, and binary already symlink to /usr/local/bin/playio-vpnc +$ playio-vpnc version + +#========================================================== +#### USE DOCKER ------------------------------------------- +# build amd64 arch +$ ./scripts/docker.vpntool.sh c + +### Build multiple arch +# Check your docker linux +$ docker buildx ls +NAME/NODE DRIVER/ENDPOINT STATUS PLATFORMS +multiarch * docker-container + multiarch0 unix:///var/run/docker.sock running linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6 + +# default are: amd64/armv7 +$ ./scripts/docker.vpntool.sh c true +# custom arch: armv7/arm64 +$ PLATFORMS="linux/arm/v7,linux/arm64" ./scripts/docker.vpntool.sh c true +---- + +=== VPNC Deployer + +link:https://github.com/play-iot/iot-vpn/blob/main/cli/ansible/docker/vpnc-deployer.Dockerfile[vpnc-deployer.Dockerfile] + +[,bash] +---- +./scripts/docker.vpntool.sh ddns +---- + +Please read xref:./cli/ansible/README.adoc[VPNC Deployer] to see how it works based on `ansible` and `docker` + +=== VPN DDNS + +link:https://github.com/play-iot/iot-vpn/blob/main/cli/python/docker/vpnddns.Dockerfile[vpnddns.Dockerfile] + +[,bash] +---- +./scripts/docker.vpntool.sh ddns +---- + +Please read xref:./cli/k8s/ddns/README.adoc[VPN DDNS k8s] to see sample `k8s` deployment + +=== Implementation + +Please consume xref:./cli/python/DEV.adoc[vpnc-dev] + +== VPN manager + +TBD diff --git a/docs/cli/ansible/README.adoc b/docs/cli/ansible/README.adoc new file mode 100644 index 0000000..eeb7f04 --- /dev/null +++ b/docs/cli/ansible/README.adoc @@ -0,0 +1,201 @@ += Deploy VPN client + +== Usage + +=== Installation + +* Download the latest version `vpnc-deployer-cli` in https://github.com/play-iot/iot-vpn/releases[playio-vpn/releases] and copy to anywhere in *YOUR LINUX COMPUTER* +* Install https://docs.docker.com/engine/install[`docker`] and https://docs.docker.com/compose/install/[`docker-compose`] + +[TIP] + +For convenient, setup download tool https://github.com/zero88/gh-release-downloader[ghrd] to quick download artifact by version on GitHub. +This is setup script for `Ubuntu`/`Debian` distro + +[,bash] +---- +export GHRDVER=1.1.2 && sudo curl -L https://github.com/zero88/gh-release-downloader/releases/download/v$GHRDVER/ghrd -o /usr/local/bin/ghrd \ + && sudo chmod +x /usr/local/bin/ghrd \ + && sudo ln -sf /usr/local/bin/ghrd /usr/bin/ghrd \ + && sudo apt install jq -y \ + && unset GHRDVER +---- + +==== Download tool + +This is a script that using `ghrd`. +For example: `VPNCVER=v0.9.4` + +[,bash] +---- +export VPNCVER=v0.9.4 \ + && ghrd vpnc-deployer-cli -r vpnc-deployer/$VPNCVER -o /tmp play-iot/iot-vpn \ + && sudo mkdir -p /app \ + && sudo mv /tmp/vpnc-deployer-cli /app/vpnc-deployer-cli \ + && sudo ln -sf /app/vpnc-deployer-cli /usr/local/bin/vpnc-deployer-cli \ + && unset VPNCVER +---- + +=== Workflow + +Assume sample workflow inputs: + +|=== +| Input | Value | Description + +| `deployer_dir` +| `/app/vpnc-deployer` +| A deployment dir in your computer + +| `vpnc_version` +| `0.9.4` +| A VPNC release version + +| `customer_code` +| `enviro` +| An sample for customer code + +| `private_cloud_dns` +| `proxy.cloud.enviro` +| A private cloud DNS for each customer. +If customer have not yet private cloud, use `google.com` +|=== + +Repeat this workflow for each customer with update corresponding to `customer_code` and `private_cloud_dns` If new `vpnc` version is released, need to update also. + +==== Init step + +This step use information above. +Please check it carefully. + +[,bash] +---- +$ cat >> ~/.bashrc <' in which command can be one of [setup,state,rollout,extend,undeploy] +DONE!!! +---- + +=== Update target machine hosts + +Update `-hosts.yml` as `init` step output. +In sample context is: `/app/vpnc-deployer/inventory/enviro-hosts.yml` + +[,yaml] +---- +all: +children: + device: + hosts: + : + ansible_host: + : + ansible_host: + ansible_port: + ansible_user: + ansible_password: + vars: + ansible_port: + ansible_user: + ansible_password: +---- + +*Importance* + +* Replace `device_name_*` to vpn user format. +For example: `n000001`, `n000002` +* Replace `device_ip_*` to host ip that corresponding to `vpn_user`. +For example: `192.168.10.15` for `n000001`. +* Replace `device_port_*` to SSH port that corresponding to `vpn_user`. +For example: `2022` for `n000001`. +* Replace `device_user_*` to SSH user in `sudo` role that corresponding to `vpn_user`. +For example: `pi` for `n000001`. +* Replace `device_password_*` to SSH password that corresponding to `vpn_user`. + +=== Update target VPN credentials + +Update `-credentials.json` as `init` step output. +In sample context is: `/app/vpnc-deployer/enviro-credentials.json` + +[,json] +---- +{ +"": { + "vpn_server": "", + "vpn_port": "", + "vpn_hub": "", + "vpn_account": "", + "vpn_auth_type": "", + "vpn_user": "", + "vpn_password": "", + "vpn_cert_key": "", + "vpn_private_key": "" + } +} +---- + +*Importance* + +* You can test by your local computer with `user`/`password` +* In `production`, this file will be provided by administrator per customer + +=== Setup VPN client + +[,bash] +---- +./vpnc-deployer.sh -e enviro setup +---- + +It will show output to console, then don't close it by `Ctrl+C` After the progress finished, it will show something like that + +[,bash] +---- +vpnc-deployer_1 | PLAY RECAP ********************************************************************* +vpnc-deployer_1 | n000002 : ok=14 changed=3 unreachable=0 failed=0 skipped=1 rescued=0 ignored=0 +vpnc-deployer_1 | n000003 : ok=14 changed=3 unreachable=0 failed=0 skipped=1 rescued=0 ignored=0 +---- + +* If output show `unreachable=1`, please check your connection to target devices (`ip`/`port`/`username`/`password`) +* If output show `failed=1`, please copy a log file in `/tmp/out/ansible.log` then send to @zero88` + +== Development + +[,bash] +---- +ansible-inventory --graph +---- + +Run this playbook first to ensure the default `python` path exists on target hosts for ansible to lookup: + +[,bash] +---- +ansible-playbook wf-ensure-python.yml +---- + +Then: + +[,bash] +---- +ansible-playbook wf-vpnc-rollout.yml -e 'debug=1' -e '{"args_vpn_state_test_domains": ["google.com"]}' +---- + +=== Docker + +* See `docker-compose` dev version link:https://github.com/play-iot/iot-vpn/blob/main/docker/vpnc-deployer-dkc.yml[here] diff --git a/docs/cli/python/DEV.adoc b/docs/cli/python/DEV.adoc new file mode 100644 index 0000000..57d81d9 --- /dev/null +++ b/docs/cli/python/DEV.adoc @@ -0,0 +1,224 @@ += Development + +== Develop VPN client tool + +=== Run in dev + +[,bash] +---- +# Navigate to python source +cd cli/python +# After pipenv shell +python -m src.client.cmd_client -h +# OR +python index.py client -h +Usage: cmd_client.py [OPTIONS] COMMAND [ARGS]... + +VPN Client tool to install Softether VPN Client and setup VPN connection + +Options: + -h, --help Show this message and exit. + +Commands: + add Add new VPN Account + command Execute Ad-hoc VPN command + connect Connect to VPN connection with VPN account + detail Get detail VPN Account configuration + disconnect Disconnect VPN connection with VPN account + install Install VPN client and setup *nix service + list Get all VPN Accounts + log Get VPN log + status Get current VPN status + trust Trust VPN Server cert + uninstall Stop and disable VPN client and *nix service + version VPN Version +---- + +* Using `download -h` (it is invisible for end-user) to download binary in `src/client/resources/debug` folder, then every `command`, it is mandatory to add `--dev` for using VPN binary in `src/client/resources/debug` folder. +* `start`/`stop` command also invisible because it is system command, that avoids confusing to end-user + +=== Build client tool to binary + +[,bash] +---- +# After pipenv shell +# Download and compile VPN client binary. Default is `linux-x64` +python -m src.client.cmd_client download +# Build to CLI binary +pyinstaller src/client/cmd_client.py -n playio-vpnc --clean --onefile --add-data src/client/resources/*:resources/ +---- + +== Develop VPN tool + +VPN Tool covers all aspect of VPN from `server`/`hub`/`client`/`secret` + +=== Run in dev + +[,bash] +---- +# After pipenv shell +python index.py -h +Usage: index.py [OPTIONS] COMMAND [ARGS]... + + VPN Helper + +Options: + -h, --help Show this message and exit. + +Commands: + client VPN Client tool to install Softether VPN Client and setup VPN connection + hub VPN Hub Tool to add/modify SoftEther VPN users and groups. + secret Secret utils + server VPN Server tool + vpn Tool to add/modify SoftEther VPN users and groups. +---- + +=== Build VPN client tool to binary + +[,bash] +---- +# After pipenv shell +pyinstaller src/client/cmd_client.py -n playio-vpnc --clean --onefile \ + --add-data src/client/resources/*:resources/ +---- + +== Develop MAC tool + +[,bash] +---- +python -m src.command.cmd_mac -h + +Usage: cmd_mac.py [OPTIONS] COMMAND [ARGS]... + + MAC generator + +Options: + -h, --help Show this message and exit. + +Commands: + generate Generate MAC + last Get last MAC sequence in given file + validate Validate MAC duplication in given file +---- + +=== Build client tool to binary + +[,bash] +---- +# After pipenv shell +pyinstaller src/command/cmd_mac.py -n playio-mac --clean --onefile +---- + +=== MAC Usage + +[,bash] +---- +playio-mac generate -h +Usage: playio-mac generate [OPTIONS] [OUTPUT] + + Generate MAC + +Options: + -n, --quantity INTEGER The quantity that you need [default: 1] + -o, --overwrite Append to file [default: False] + --asix1 First ASIX: "F8:E4:3B" + --asix2 Second ASIX: "00:0E:C6" + --oui TEXT Enforces a specific an organization unique identifier (like F8:E4:3B for ASIX) + --seq TEXT From last sequence. Use with --asix1/--asix2/--oui + --rand Random MAC instead of sequence [default: False] + --uaa Generates a universally administered address (instead of LAA otherwise) [default: False] + --multicast Generates a multicast MAC (instead of unicast otherwise) [default: False] + --byte-fmt TEXT The byte format. Set to %02X for uppercase hex formatting. [default: %02x] + --sep TEXT The byte separator character [default: :] + -h, --help Show this message and exit. +---- + +=== MAC Usage + +* Generate in random mode + +[,bash] +---- +# Print to console +> playio-mac generate --rand -n 10 + +# Write to file +> playio-mac generate --rand -n 10 playio.mac + +# Overwrite file +> playio-mac generate --rand -n 5 -o playio.mac + +# Generate random MAC with organization unique identifier +> playio-mac generate --rand -n 10000 --oui 00:0E:C6 playio.mac + +# Validate MAC collision +> playio-mac validate playio.mac +Duplicated key: 02:0e:c6:91:14:42 in lines [1229, 2793] +Duplicated key: 02:0e:c6:82:19:5c in lines [2073, 5991] +Duplicated key: 02:0e:c6:d2:fa:20 in lines [3285, 4060] +Duplicated key: 02:0e:c6:ec:8f:49 in lines [4162, 5469] +Duplicated 4 keys +---- + +* Generate in with `organization unique identifier` and `sequence` + +[,bash] +---- +# Write based on ASIX +> playio-mac generate --asix1 -n 5 +f8:e4:3b:00:00:00 +f8:e4:3b:00:00:01 +f8:e4:3b:00:00:02 +f8:e4:3b:00:00:03 +f8:e4:3b:00:00:04 + +# Write to file then keep it for generate MAC sequently +> playio-mac generate --asix1 -n 5 playio.mac +## Check last MAC +> playio-mac last playio.mac +f8:e4:3b:00:00:04 +## Generate next 5 from last sequence +> playio-mac generate --asix1 -n 5 --seq $(playio-mac last playio.mac) playio.mac +> cat playio.mac +f8:e4:3b:00:00:00 +f8:e4:3b:00:00:01 +f8:e4:3b:00:00:02 +f8:e4:3b:00:00:03 +f8:e4:3b:00:00:04 +f8:e4:3b:00:00:05 +f8:e4:3b:00:00:06 +f8:e4:3b:00:00:07 +f8:e4:3b:00:00:08 +f8:e4:3b:00:00:09 +---- + +* Copy `MAC` from current NIC with override option from `OUI` + +[,bash] +---- +> playio-mac copy -h +Usage: playio-mac mac copy [OPTIONS] [NIC] + Copy MAC with override OUI + +Options: + --asix1 First ASIX: "F8:E4:3B" + --asix2 Second ASIX: "00:0E:C6" + --oui TEXT Enforces a specific an organization unique identifier (like F8:E4:3B for ASIX) + --byte-fmt TEXT The byte format. Set to %02X for uppercase hex formatting. [default: %02x] + --sep TEXT The byte separator character [default: :] + -h, --help Show this message and exit. + +## Default NIC is `eth0` +> playio-mac copy --asix1 +f8:e4:3b:86:71:1c + +> playio-mac copy --asix2 wlp4s0 +00:0e:c6:86:71:1c +---- + +*Reference*: http://standards-oui.ieee.org/oui/oui.txt + +*Note*: + +* Have 2 `asix` so we have 2 options `--asix1` and `--asix2` +* Because generate with `organization unique identifier` and `random` mode still having collision so should use `MAC sequence` and keep `playio.mac` in repository to reference later diff --git a/docs/cli/python/OVERVIEW.adoc b/docs/cli/python/OVERVIEW.adoc new file mode 100644 index 0000000..a50d841 --- /dev/null +++ b/docs/cli/python/OVERVIEW.adoc @@ -0,0 +1,79 @@ += PlayiO VPN overview + +== External connection + +VPN infrastructure provide private tunnel via Internet connection to our servers. + +[NOTE] + +Our client will run on beagleboard device, which is running Debian on `armv7`, testing client scripts may need a real device. + +== Development script + +This is collection of script to bootstrap, manage, setup softether-vpn server. + +=== Requirements + +* https://www.softether.org/4-docs/1-manual/4._SoftEther_VPN_Client_Manual/4.4_Making_Connection_to_VPN_Server#4.4.3_Connection_Via_HTTP_Proxy_Server[`Connection via HTTPS Proxy`] VPN connection uses `SoftEther VPN protocol` over `HTTPS`, backed by `reverse proxy`, `SSL` is provided by https://letsencrypt.org/[`Letsencrypt`] +* VPN secure connection with https://www.softether.org/4-docs/1-manual/4._SoftEther_VPN_Client_Manual/4.4_Making_Connection_to_VPN_Server#4.4.5_Server-Certificate_Verification[Certificate Verification]. +VPN server certificate is generated by us that is link:https://en.wikipedia.org/wiki/Root_certificate#targetText=In%20cryptography%20and%20computer%20security,public%20key%20infrastructure%20(PKI).[`Root CA`] + ** Use `TLS 1.2` + ** https://en.wikipedia.org/wiki/Cipher_suite[Cipher suite]: `ECDHE-RSA-AES256-GCM-SHA384` + +== Internal communication + +* VPN connection type: https://www.softether.org/4-docs/1-manual/1._SoftEther_VPN_Overview/1.4_VPN_Processing_Principle_and_Communication_Method#1.4.7_Remote_Access_VPN[Remote Access VPN] +* Separate customers to `Virtual Hubs`. +* `Virtual Hubs` are isolated to each other. + +== Virtual Hub setup + +=== IP network + +Enable `secureNAT` + +* DHCP IP scope (NAT subnet): `10/8 subnet` +* Hub virtual IP (virtual NAT gateway): `10.0.0.1` +* IP configuration push to client: + ** `Corporate DNS`: IP of Corp's DNS servers + ** Optional Public Google DNS `8.8.8.8` + ** Static routes: ++ +|=== +| Internal resource | Destination network | Net mask | Gateway + +| Corporate DNS server +| +| 255.255.255.255 +| 10.0.0.1 + +| Corporate VPN subnet +| 192.168.0.0 +| 255.255.255.0 +| 10.0.0.1 +|=== ++ +[IMPORTANT] +*And all necessary routes to `internal resource subnets` are defined for a customer separately. + +=== User authentication + +* Define groups and users for each customer +* Authentication method + ** Edge device: https://www.softether.org/4-docs/1-manual/2._SoftEther_VPN_Essential_Architecture/2.2_User_Authentication#2.2.6_Signed_Certificate_Authentication[`Signed certificate`] that is signed by our <> + *** Each device has one dedicated user + *** Each device has each `VPN certificate` key + *** Each device has each `ssh` public/private key + ** (Optional) Interactive user: `basic password` + +=== Virtual Hub security policy + +Status: `WIP` + +[%interactive] + +* [ ] Define hub admin security policy + +* [ ] Define security policy and apply to group + +* [ ] Define hub extended options diff --git a/docs/cli/python/src/client/VPNC_README.adoc b/docs/cli/python/src/client/VPNC_README.adoc new file mode 100644 index 0000000..093f2b1 --- /dev/null +++ b/docs/cli/python/src/client/VPNC_README.adoc @@ -0,0 +1,233 @@ += Play-iO VPN client CLI + +Play-iO VPN client CLI for popular Linux distro and architecture. +That support + +* Auto setup and register VPN service on `*Unix` system +* Auto connect and lease VPN private IP +* Auto manage `private DNS` from VPN network + +== Installation + +Download the latest version in https://github.com/play-iot/iot-vpn/releases[vpnc/releases] with tag in format `vpnc/v[semantic-version]`. + +* `playio-vpnc.armv7.zip` for IoT device: RaspberryPi, BeagleBone, etc... +* `playio-vpnc.amd64.zip` for user computer: support Ubuntu 18/20, Debian 8/9/10 + +https://thekelleys.org.uk/dnsmasq/doc.html[dnsmasq] is used as local DNS caching to resolve DNS from private VPN network. +Currently, `dnsmasq` can be setup and auto download when installing `vpnclient` (only support `Ubuntu`/`Debian`/`Raspibian`/`Fedora`/`CentOS` in this time, if you are using another Linux distro, please install `dnsmasq` manually) + +=== Tips + +For convenient, setup download tool https://github.com/zero88/gh-release-downloader[ghrd] to quick download artifact by version on GitHub. + +This is setup script for Ubuntu/Debian distro + +[,bash] +---- +export GHRDVER=1.1.2 && sudo curl -L https://github.com/zero88/gh-release-downloader/releases/download/v$GHRDVER/ghrd -o /usr/local/bin/ghrd \ + && sudo chmod +x /usr/local/bin/ghrd \ + && sudo ln -sf /usr/local/bin/ghrd /usr/bin/ghrd \ + && sudo apt install jq -y \ + && unset GHRDVER +---- + +=== Download and setup VPN client + +This is a script that using `ghrd`. +You need to know VPN version and target system (to identify architecture edition) then subtitle to `VPNCVER` and `VPNCARCH` in a below script. + +For example: `VPNCVER=v0.9.1` and `VPNCARCH=armv7` (currently, one of `armv7` and `amd64`) + +[,bash] +---- +export VPNCVER=v0.9.1 && export VPNARCH=armv7 \ + && ghrd -a ".*$VPNARCH.*" -x -r "vpnc/$VPNCVER" -o /tmp play-iot/iot-vpn \ + && sudo mkdir -p /app \ + && sudo unzip -o -d /app /tmp/playio-vpnc*.zip \ + && sudo ln -sf /app/playio-vpnc /usr/local/bin/playio-vpnc \ + && unset VPNCVER && unset VPNARCH +---- + +Verify: + +[,bash] +---- +$ playio-vpnc version +INFO : VPN version : v4.29-9680-rtm +INFO : CLI version : 0.9.1 +INFO : Hash version: 2465e648 +------------------------------------------------------- +---- + +== Usage + +* `playio-vpnc -h` for more information ++ +[,bash] +---- +$ playio-vpnc -h +Usage: playio-vpnc [OPTIONS] COMMAND [ARGS]... + + CLI tool to install VPN Client and setup VPN connection + +Options: + -h, --help Show this message and exit. + +Commands: + about Show VPN software info + add Add new VPN Account + connect Connect to VPN connection by given VPN account + delete Delete one or many VPN account + detail Get detail VPN configuration and status by one or many accounts + disconnect Disconnect VPN connection + install Install VPN client and setup *nix service + list Get all VPN Accounts + log Get VPN log + set-default Set VPN default connection in startup by given VPN account + status Get current VPN status + trust Trust VPN Server cert + uninstall Stop and disable VPN client and *nix service + upgrade Upgrade VPN client + version VPN Version +---- + +* To interact with any command, please use `playio-vpnc -h` to see help documentation. +For example: ++ +[,bash] +---- +playio-vpnc install -h +Usage: playio-vpnc install [OPTIONS] + + Install VPN client and setup *nix service + +Options: + --auto-startup Enable auto-startup VPN service [default: False] + --auto-dnsmasq Give a try to install dnsmasq [default: False] + --dnsmasq / --no-dnsmasq By default, dnsmasq is used as local DNS cache. Disabled it if using default System DNS + resolver [default: True] + + -dd, --vpn-dir TEXT VPN installation directory [default: ("/app/vpnclient" or from "env.VPN_HOME")] + -dn, --service-name TEXT VPN Service name [default: playio-vpn] + -ds, --service-dir TEXT Linux Service directory + -f, --force If force is enabled, VPN service will be removed then reinstall without backup [default: + False] + + -v, --verbose Enables verbose mode + -h, --help Show this message and exit. +---- + +* To connect VPN server, you must provide + ** `VPN Host` HTTPS VPN server. + ** `VPN Port` Default is `443`. + ** `VPN Hub` It is multi-tenant option, normally it is `customer` code. + ** `Authentication` A login credential to appropriate VPN host and VPN Hub. +Credential type can be `password` or `cert` +* After connect VPN connection (See <>), VPN client will be registered as linux service, then you can manage it as normal linux service with some basic linux commands ++ +[,bash] +---- +sudo systemctl status playio-vpn # service status +sudo systemctl restart playio-vpn # restart service +sudo journctl -u playio-vpn +---- + +=== VPN workflow + +. Normal workflow + +[,bash] +---- + # Setup VPN client service + $ playio-vpnc install # pass "--auto-dnsmasq" to try installing `dnsmasq` internally + + # Add VPN account then open VPN session and start VPN service + $ playio-vpnc add