wallenstein/ztncui
1
0
Fork 0
mirror of https://github.com/key-networks/ztncui.git synced 2025-06-07 18:53:45 +02:00
Code Issues Projects Releases Wiki Activity

Update README.md

Browse source
This commit is contained in:
MAXimized490 2024-10-21 02:00:43 -05:00 • committed by GitHub
parent 1b2284864d
commit 2ed3b872a2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 116 additions and 121 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

227
README.md
View file

@ -12,87 +12,105 @@ Instructions for installing on Linux from RPM or DEB packges are available at [k
## Docker Container Image ## Docker Container Image
See [https://github.com/key-networks/ztncui-aio](https://github.com/key-networks/ztncui-aio) See [https://github.com/key-networks/ztncui-aio](https://github.com/key-networks/ztncui-aio)
## Getting Started # Local Installation Guide
> [!WARNING]
> ztncui has been developed on a Linux platform and expects the ZT home directory to be in `/var/lib/zerotier-one`.
### Note > [!NOTE]
Relative directory references below are relative to the cloned ztncui directory. > Paths are relative to the cloned ztncui directory.
### Prerequisites ## Prerequisites
* ztncui is a [node.js](https://nodejs.org) [Express](https://expressjs.com) application that requires [node.js](https://nodejs.org) v14. **ZeroTier One**<br>
[ZeroTier One](https://www.zerotier.com/download/) must be installed on the same machine. This will run as the network controller to establish ZeroTier networks.
* ztncui uses argon2 for password hashing. Argon2 needs the following: **Node.js**<br>
1. g++ ztncui is a [Node.js](https://nodejs.org) [Express](https://expressjs.com) application. It requires v14.
2. node-gyp, which can be installed with:
```shell **argon2**<br>
Used for password hashing. Argon needs g++ and node-gyp.
```
sudo npm install -g node-gyp sudo npm install -g node-gyp
``` ```
* ztncui requires [ZeroTier One](https://www.zerotier.com/download.shtml) to be installed on the same machine. This will run as the network controller to establish ZeroTier networks. ## Installing
### Step 1: Clone the Repository
* ztncui has been developed on a Linux platform and expects the ZT home directory to be in `/var/lib/zerotier-one`. Clone the repo on a machine running ZeroTier One.
### Installing
##### 1. Clone the repository on a machine running ZeroTier One:
```shell ```shell
git clone https://github.com/key-networks/ztncui git clone https://github.com/key-networks/ztncui
``` ```
##### 2. Install the [node.js](https://nodejs.org) packages: ### Step 2: Install Node.js Packages
```shell ```shell
cd ztncui/src cd ztncui/src &&
npm install npm install
``` ```
##### 3. authtoken.secret ## Configuring
### Step 3: Make .env File
The app needs to know the zerotier-one authtoken.secret.
###### Make a .env file
In the root of the ztncui directory, create a `.env` file with the content: In the root of the ztncui directory, create a `.env` file with the content:
``` ```
ZT_TOKEN=######################## ZT_TOKEN=
NODE_ENV=production
``` ```
Where: **ZT_TOKEN**<br>
* ######################## is the token string. The app needs to know the zerotier-one authtoken.secret which can be found at `/var/lib/zerotier-one/authtoken.secret`. Paste this token after `ZT_TOKEN=` in the `.env` file.
After all edits to the `.env file` (see other options below), make the `.env` readable by the user running ztncui only: **MODE_ENV**<br>
```shell To run the server in production mode, set this to `production`. While not required, the template engine always re-compiles the pug file when rendering without this (taking ~200 ms!).
chmod 400 .env
chown ztncui.ztncui .env
```
##### 4. Zerotier-one API port #### Optional Environment Variables
**ZT_ADDR**<br>
You can specify in the `.env` file a different address for the zerotier-one API (which defaults to localhost:9993): You can specify a different address for the zerotier-one API (which defaults to localhost:9993):
``` ```
ZT_ADDR=localhost:9995 ZT_ADDR=localhost:9995
``` ```
**HTTP_ALL_INTERFACES**<br>
The app can be made to listen on all interfaces for HTTP requests by setting `HTTP_ALL_INTERFACES`, e.g.:
```
HTTP_ALL_INTERFACES=yes
```
Note that HTTP traffic is unencrypted, so this should only be done on a secure network, otherwise usernames and passwords will be exposed in plain text over the network.
##### 4. Run in production mode **HTTP_PORT**<br>
To run the server in production mode, add the following to the `.env` file (see 3B above): The app runs on TCP port 3000 by default. If port 3000 is already in use, you can specify a different port, e.g.:
```
NODE_ENV=production
```
Without this, the template engine always re-compiles the pug file when rendering (taking ~200 ms!)
##### 5. Copy the default passwd file
To prevent git from over-writing your password file every time you pull updates from the repository, the etc/passwd file has been added to .gitignore. So you need to copy the default file after the first time you do a git clone. All these things ideally need to be done with a package installer script:
```shell
cp -v etc/default.passwd etc/passwd
```
##### 6. Start the app manually:
```shell
npm start
```
This will run the app on TCP port 3000 by default. If port 3000 is already in use, you can specify a different port in the `.env` file (see 3B above), e.g.:
``` ```
HTTP_PORT=3456 HTTP_PORT=3456
``` ```
##### 7. Start the app automatically **HTTPS_PORT & HTTPS_HOST**<br>
To start the app automatically, something like [PM2](http://pm2.keymetrics.io) can be used. Install it with: The app can be made to listen on all interfaces for HTTPS requests by specifying `HTTPS_PORT`, e.g.:
```
HTTPS_PORT=3443
```
The app can be made to listen on a specific interface for HTTPS requests by specifying `HTTPS_HOST` (the host name or IP address of the interface) along with `HTTPS_PORT`, e.g.:
```
HTTPS_PORT=3443
HTTPS_HOST=12.34.56.78
```
#### Set Permissions
After all edits to the `.env` file have been made, make the `.env` readable by the user running ztncui only:
```shell
chmod 400 .env
chown ztncui:ztncui .env
```
### Step 4: Copy Default Passwd File
> [!CAUTION]
> Do not confuse `etc/passwd` with `/etc/passwd`!
To prevent git from overwriting your password file every time you pull updates from the repository, the `etc/passwd` file has been added to `.gitignore`. The default file will need to be copied after the first time you do a git clone.
```shell
cp -v etc/default.passwd etc/passwd
```
### Step 5: Start the App
#### Manually
```shell
npm start
```
#### Automatically (with [PM2](http://pm2.keymetrics.io))
To start the app automatically, something like PM2 can be used. Install it with:
```shell ```shell
sudo npm install -g pm2 sudo npm install -g pm2
``` ```
@ -109,53 +127,23 @@ pm2 startup
PM2 will then give you a command to execute to configure automatic startup of PM2 for your system. PM2 will then give you a command to execute to configure automatic startup of PM2 for your system.
Save the current PM2 process list so that ztncui will restart across reboots: Save the current PM2 process list so that ztncui will restart across reboots:
```shell ```shell
pm2 save pm2 save
``` ```
### Step 6: Access the App
##### 8. Test access on http://localhost:3000 #### HTTP
If the machine has a GUI and GUI web browser, then use it to access the app, otherwise use a text web browser like Lynx or a CLI web browser like curl: This app listens for HTTP requests on the looback interface (default port 3000). If the host machine has a GUI and GUI web browser then use it to access the app. The default URL will be [http://localhost:3000](http://localhost:3000). Alternatively, use a text web browser like Lynx or a CLI web browser like curl:
```shell ```shell
curl http://localhost:3000 curl http://localhost:3000
``` ```
You should see the front page of the app (or the raw HTML with curl). You should see the front page of the app (or the raw HTML with curl).
#### HTTPS
##### 9. Remote access via HTTPS The app can be reverse proxied by Nginx (which can proxy the HTTP as HTTPS), or accessed over an SSH tunnel as described below.
This app listens for HTTP requests on the looback interface (default port 3000). It can be reverse proxied by Nginx (which can proxy the HTTP as HTTPS), or accessed over an SSH tunnel as described below. ##### TLS Certificate
For HTTPS you will need a TLS (SSL) certificate and private key pair. There are a few options:
The app can be made to listen on all interfaces for HTTP requests by setting HTTP_ALL_INTERFACES in the `.env` file, e.g.: 1. By default, if there is no existing TLS certificate and private key pair, the RPM and DEB packages automatically generate a self-signed certificate / private key pair. If you are running directly from source, then generate a self-signed certificate as follows:
```
HTTP_ALL_INTERFACES=yes
```
Note that HTTP traffic is unencrypted, so this should only be done on a secure network, otherwise usernames and passwords will be exposed in plain text over the network.
The app can be made to listen on all interfaces for HTTPS requests by specifying HTTPS_PORT in the `.env` file, e.g.:
```
HTTPS_PORT=3443
```
The app can be made to listen on a specific interface for HTTPS requests by specifying HTTPS_HOST (the host name or IP address of the interface) in the `.env` file, e.g.:
```
HTTPS_HOST=12.34.56.78
```
If HTTPS_HOST is not specified, but HTTPS_PORT is specified, then the app will listen for HTTPS requests on all interfaces.
###### Summary of listening states
| Environment variable | Protocol | Listen On | Port |
| :------------------: | :------: | :-------: | :--: |
| [none] | HTTP | localhost | 3000 |
| HTTP_PORT | HTTP | localhost | HTTP_PORT |
| HTTP_ALL_INTERFACES | HTTP | all interfaces | HTTP_PORT || 3000 |
| HTTPS_PORT | HTTPS | all interfaces | HTTPS_PORT |
| HTTPS_HOST | HTTPS | HTTPS_HOST | HTTPS_PORT |
###### TLS Certificate
For HTTPS you obviously need a TLS (SSL) certificate and private key pair. There are a few options:
1. By default, if there is no existing TLS certificate and private key pair, the RPM and DEB packages automatically generate a self-signed certificate / private key pair.
2. If you are running directly from source, then generate a self-signed certificate as follows:
```shell ```shell
cd etc/tls cd etc/tls
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout privkey.pem -out fullchain.pem openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout privkey.pem -out fullchain.pem
@ -163,12 +151,8 @@ For HTTPS you obviously need a TLS (SSL) certificate and private key pair. Ther
Fill in the required details as prompted. Fill in the required details as prompted.
The advantage of this option is that it is quick and easy to generate the certificate / private key pair. The disadvantage is that your web browser will give you a warning that it cannot verify the certificate. You can override this warning and make a temporary exception. The advantage of this option is that it is quick and easy to generate the certificate / private key pair. The disadvantage is that your web browser will give you a warning that it cannot verify the certificate. You can override this warning and make a temporary exception.
2. Buy a certificate and store the private key as `etc/tls/privkey.pem` and the full certificate chain as `etc/tls/fullchain.pem`. They need to be in PEM format.
3. Buy a certificate: 3. Get a free certificate from Letsencrypt.org:
You will need to store the private key as `etc/tls/privkey.pem` and the full certificate chain as `etc/tls/fullchain.pem`. They need to be in PEM format.
4. Get a free certificate from Letsencrypt.org:
a. Install certbot by following the instructions at certbot.eff.org: a. Install certbot by following the instructions at certbot.eff.org:
@ -197,10 +181,9 @@ For HTTPS you obviously need a TLS (SSL) certificate and private key pair. Ther
d. Take note of the options for renewing Letsencrypt certificates and implement an appropriate strategy. d. Take note of the options for renewing Letsencrypt certificates and implement an appropriate strategy.
###### Test HTTPS access ###### Test HTTPS access
Once you have a certificate at `etc/tls/fullchain.pem` and private key at `etc/tls/privkey.pem`, you should be able to access ztncui over HTTPS on the port specified by HTTPS_PORT. Once you have a certificate at `etc/tls/fullchain.pem` and private key at `etc/tls/privkey.pem`, you should be able to access ztncui over HTTPS on the port specified by `HTTPS_PORT`.
##### Remote access via SSH
##### 10. Remote access via SSH
###### SSH tunnel from Linux / Unix / macOS client ###### SSH tunnel from Linux / Unix / macOS client
An SSH tunnel can be established with: An SSH tunnel can be established with:
```shell ```shell
@ -228,32 +211,27 @@ Open PuTTY and configure as follows:
Once the SSH tunnel has been established, access the ztncui web interface in a web browser on your local machine at: http://localhost:3333 Once the SSH tunnel has been established, access the ztncui web interface in a web browser on your local machine at: http://localhost:3333
## Usage # Usage
### User accounts ## User Accounts
Once you have access to the web UI of ztncui, log in as user **admin** with password **password**. Once you have access to the web UI of ztncui, log in as user **admin** with password **password**.
You will be prompted to change the default password. You will be prompted to change the default password.
It's a good idea to create your own username and delete the default admin account. You can do this by clicking on the **Users** tab and then the **Create user** tab. Note that you then have to log out and log in as the new user before you can delete the default admin account. It's a good idea to create your own username and delete the default admin account. You can do this by clicking on the **Users** tab and then the **Create user** tab. Note that you then have to log out and log in as the new user before you can delete the default admin account.
### Networks ## Networks
Click on the **Home** tab to get to the network controller home page. From there you can click on the **Networks** tab to see the existing networks configured on the network controller (probably none if you have just set it up). Click on the **Home** tab to get to the network controller home page. From there you can click on the **Networks** tab to see the existing networks configured on the network controller (probably none if you have just set it up).
#### Create a new network ### Create a New Network
Click on the **Add network** tab to create a new ZeroTier network that is controlled by the network controller. Give it a name and click **Create Network**. You will then be taken back to the **Networks** page that lists all the networks on the controller. Click on the **Add network** tab to create a new ZeroTier network that is controlled by the network controller. Give it a name and click **Create Network**. You will then be taken back to the **Networks** page that lists all the networks on the controller.
#### Delete a network #### Easy Network Setup
On the **Networks** page, click the trash can icon to delete a network. You will be warned that this action cannot be undone. Click the **Delete** button to confirm the action.
#### Change network name
On the **Networks** page, click the name of the network to rename it.
#### Easy network setup
On the **Networks** page, click **easy setup** for the network that you want to auto-configure. Click **Generate network address** to assign a random network address, or manually enter the network address in CIDR notation. The start and end of the IP assignment pool will be automatically calculated, but these can be manually adjusted. Click **Submit** to apply the configuration. You should then get a notice that the network setup succeeded. On the **Networks** page, click **easy setup** for the network that you want to auto-configure. Click **Generate network address** to assign a random network address, or manually enter the network address in CIDR notation. The start and end of the IP assignment pool will be automatically calculated, but these can be manually adjusted. Click **Submit** to apply the configuration. You should then get a notice that the network setup succeeded.
Note that the **easy setup** only works for IPv4 at this stage. To set up IPv6, follow the **detail** link for a network from the **Networks** page and set up each property manually. Note that the **easy setup** only works for IPv4 at this stage. To set up IPv6, follow the **detail** link for a network from the **Networks** page and set up each property manually.
#### Join devices to the network ### Manage a Network
#### Join Devices to a Network
Invite users to join the network with: Invite users to join the network with:
```shell ```shell
sudo zerotier-cli join ################ sudo zerotier-cli join ################
@ -264,8 +242,7 @@ Get the user to send you their 10-digit ZeroTier address, which they can get by
```shell ```shell
sudo zerotier-cli status sudo zerotier-cli status
``` ```
#### Authorize Members on a Network
#### Authorize members on the network
On the **Networks** page, click **members** to see the devices which are trying to join the network. Use the ZeroTier address given to you by the user to identify them and name them appropriately under **Member name**. On the **Networks** page, click **members** to see the devices which are trying to join the network. Use the ZeroTier address given to you by the user to identify them and name them appropriately under **Member name**.
Then check the **Authorized** checkbox to authorize the user on the network. Then check the **Authorized** checkbox to authorize the user on the network.
@ -295,7 +272,25 @@ Note that editing of certain properties, such as rules and tags, has not been im
#### Member detail #### Member detail
On the network **detail** page and on the **members** page, if you click on the member ID, you will end up on the member detail page. On the network **detail** page and on the **members** page, if you click on the member ID, you will end up on the member detail page.
## Feedback
### Delete a Network
On the **Networks** page, click the trash can icon to delete a network. You will be warned that this action cannot be undone. Click the **Delete** button to confirm the action.
### Change Network Name
On the **Networks** page, click the name of the network to rename it.
# Reference
### Summary of listening states
| Environment variable | Protocol | Listen On | Port |
| :------------------: | :------: | :-------: | :--: |
| [none] | HTTP | localhost | 3000 |
| HTTP_PORT | HTTP | localhost | HTTP_PORT |
| HTTP_ALL_INTERFACES | HTTP | all interfaces | HTTP_PORT || 3000 |
| HTTPS_PORT | HTTPS | all interfaces | HTTPS_PORT |
| HTTPS_HOST | HTTPS | HTTPS_HOST | HTTPS_PORT |
# Feedback
Please give us your feedback... good, bad or ugly. Constructive criticism is welcomed. Please use the contact form at [key-networks.com](https://key-networks.com/) - Thanks :) Please give us your feedback... good, bad or ugly. Constructive criticism is welcomed. Please use the contact form at [key-networks.com](https://key-networks.com/) - Thanks :)
## Bug and Vulnerability Reporting ## Bug and Vulnerability Reporting