Skip to content

Commit

Permalink
Merge pull request #243 from NethServer/openvpn_rw
Browse files Browse the repository at this point in the history 
OpenVPN RW APIs
  • Loading branch information
@gsanchietti
gsanchietti authored Dec 5, 2023
2 parents b4dd47f + 2c59ed8 commit 5e42e33
Show file tree
Hide file tree
Showing 14 changed files with 995 additions and 173 deletions.
381 changes: 377 additions & 4 deletions packages/ns-api/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -903,18 +903,391 @@ Response:

Manage OpenVPN Road Warrior server.

### add-default-instance
### get-configuration

Get current server configuration:
```
api-cli ns.ovpnrw get-configuration
```

Response example for a server in routed mode:
```json
{
"proto": "udp",
"port": "1194",
"dev_type": "tun",
"topology": "subnet",
"enabled": "1",
"client_to_client": "0",
"auth": "SHA256",
"cipher": "AES-256-GCM",
"tls_version_min": "1.2",
"ns_auth_mode": "certificate",
"ns_bridge": "lan",
"server": "192.168.101.0/24",
"ns_public_ip": [
"192.168.100.238"
],
"ns_redirect_gateway": "0",
"ns_local": [
"192.168.101.0/24",
"192.168.100.0/24"
],
"ns_dhcp_options": []
}
```

Response example for a server in bridged mode:
```json
{
"proto": "udp",
"port": "1194",
"dev_type": "tap",
"topology": "subnet",
"enabled": "1",
"client_to_client": "0",
"auth": "SHA256",
"cipher": "AES-256-GCM",
"tls_version_min": "1.2",
"ns_auth_mode": "certificate",
"ns_bridge": "lan",
"ns_public_ip": [
"192.168.100.238"
],
"server": "",
"ns_redirect_gateway": "0",
"ns_local": [
"192.168.100.0/24"
],
"ns_dhcp_options": [
{
"option": "NBDD",
"value": "1.2.3.4"
}
],
"ns_pool_start": "192.168.100.240",
"ns_pool_end": "192.168.100.242"
}
```
### list-users

List existing users with their status:
```
api-cli ns.ovpnrw list-users
```

Response example:
```json
{
"users": [
{
"enabled": "1",
"instance": "ns_roadwarrior",
"username": "giacomo",
"password": "mypass",
"connected": false,
"ipaddr": "1.2.3.4",
"expiration": 2012460421,
"expired": false,
},
{
"instance": "ns_roadwarrior",
"enabled": "1",
"password": "mypass",
"ipaddr": "192.168.101.44",
"2fa": "eeea7e12f45c48709525a21985d9a2605f13a451b9ec342521d2fd53dd22f5ec",
"username": "giacomo2",
"connected": true,
"real_address": "192.168.100.1",
"virtual_address": "192.168.101.44",
"bytes_received": "3703",
"bytes_sent": "3091",
"since": 1701701676,
"expiration": 2012741635,
"expired": false
}
]
}
```

The following fields may not be present:
- `password`
- `ipaddr`

If `connected` field is `true`, the user object should contain also:
- `real_address`, the remote address
- `virtual_address`
- `bytes_received`
- `bytes_sent`
- `since`, connected since the given timestamp

### list-auth-modes

List authentication modes:
```
api-cli ns.ovpnrw list-auth-modes
```

Create basic instance with network and firewall configuration:
Response example:
```json
{
"options": [
"username_password",
"certificate",
"username_password_certificate",
"username_otp_certificate"
]
}
```

### list-cipher

List all available ciphers to be used inthe the `cipher` option:
```
api-cli ns.ovpnrw add-default-instance
api-cli ns.ovpnrw list-cipher
```

Response example:
```json
{ "success": true }
{
"ciphers": [
{
"name": "AES-128-CBC",
"description": "weak"
}
]
}
```

### list-digest

List availalble digests to be used inside the `auth` option:
```
api-cli ns.ovpnrw list-digest
```

Response example:
```json
{
"digests": [
{
"name": "SHA3-224",
"description": "strong"
}
]
}
```

### list-dhcp-options

List available DHCP options:
```
api-cli ns.ovpnrw list-dhcp-options
```

Response example:
```json
{
"options": [
"DNS",
"WINS",
"NBDD",
"NBT",
"NBS",
"DISABLE-NBT"
]
}
```

### list-bridges

```
api-cli ns.ovpnrw list-bridges
```
Response example:
```json
{
"bridges": [
"lan"
]
}
```

### set-configuration

Configure a routed server:
```
api-cli ns.ovpnrw set-configuration --data '{"proto":"udp","port":"1194","dev_type":"tun","topology":"subnet","enabled":"1","client_to_client":"0","auth":"SHA256","cipher":"AES-256-GCM","tls_version_min":"1.2","ns_auth_mode":"certificate","ns_public_ip":["192.168.100.238"],"server":"192.168.101.0/24","ns_redirect_gateway":"0","ns_local":["192.168.22.0/24","192.168.100.0/24"],"ns_dhcp_options":[{"option": "NBDD", "value": "1.2.3.4"}],"ns_pool_start":"","ns_pool_end":"","ns_bridge":""}}'
```

Configure a bridged server:
```
api-cli ns.ovpnrw set-configuration --data '{"proto":"udp","port":"1194","dev_type":"tap","topology":"subnet","enabled":"1","client_to_client":"0","auth":"SHA256","cipher":"AES-256-GCM","tls_version_min":"1.2","ns_auth_mode":"certificate","ns_public_ip":["192.168.100.238"],"server":"","ns_redirect_gateway":"0","ns_local":["192.168.22.0/24","192.168.100.0/24"],"ns_dhcp_options":[],"ns_pool_start":"192.168.100.239","ns_pool_end":"192.168.100.240","ns_bridge":"lan"}'
```

Valid values for `proto` field are: `udp` and `tcp-server`

Required fields for routed mode:
- `dev_type` field must be set to `tun`
- `server` field must contain a valid CIDR
- `ns_pool_start`, `ns_pool_end` and `ns_brdige` fields should be empty

Required fields for bridged mode:
- `dev_type` field must be set to `tap`
- `ns_pool_start`, `ns_pool_end` must contain a valid IP addresses; both address should be inside the bridge network, start must be greater than end
- `ns_brdige` field must contain a bridge obtained from `list-bridges` API
- `server` should be empty

The API may raise the following validation errors:
- bridge_not_found
- start_not_in_network
- end_not_in_network
- ip_already_used
- start_must_be_greater_then_end

### add-user

Create a user and generate a certficate for it:
```
api-cli ns.ovpnrw add-user --data '{"enabled": "1", "username": "myuser", "password": "mypass", "expiration": "3650", "ipaddr": "1.2.3.4"}'
```

Response example:
```json
{"result": "success"}
```

The APIs can raise the following validation errors:
- user_already_exists
- user_add_failed
- reserved_ip_must_be_in_server_network
- reserverd_ip_already_used
- reserved_ip_must_be_in_server_network

### edit-user

Edit a user and generate a certficate for it:
```
api-cli ns.ovpnrw add-user --data '{"enabled": "1", "username": "myuser", "password": "mypass", "expiration": "3650", "ipaddr": "1.2.3.4"}'
```

Response example:
```json
{"result": "success"}
```

The APIs can raise the following validation errors:
- user_not_found
- user_add_failed
- reserved_ip_must_be_in_server_network
- reserverd_ip_already_used
- reserved_ip_must_be_in_server_network


### disable-user

Disable ab existing user:
```
api-cli ns.ovpnrw disable-user --data '{"username": "myuser"}''
```

Response example:
```json
{"result": "success"}
```

Throws a validation error if the user is not found.

### enable-user

Enable an existing user:
```
api-cli ns.ovpnrw enable-user --data '{"username": "myuser"}''
```

Response example:
```json
{"result": "success"}
```

Throws a validation error if the user is not found.


### delete-user

Delete an existing user:
```
api-cli ns.ovpnrw delete-user --data '{"username": "myuser"}''
```

Response example:
```json
{"result": "success"}
```

Throws a validation error if the user is not found.

### regenerate-user-certificate

Delete current user certificate and create a new one:
```
api-cli ns.ovpnrw regenerate-user-certificate --data '{"username": "myuser", "expiration": "3650"}''
```

Response example:
```json
{"result": "success"}
```

Throws a validation error if the user is not found.

### download-user-certificate

Download the certificate chain for the given user:
```
api-cli ns.ovpnrw download-user-certificate --data '{"username": "myuser"}'
```

Response example:
```json
{
"data": "-----BEGIN CERTIFICATE-----\nMII...\n-----END PRIVATE KEY-----\n\n"}
```

Throws a validation error if the user is not found.

### download-user-configuration

Download the OpenVPN configuration with embedded certificates for the given user:
```
api-cli ns.ovpnrw download-user-configuration --data '{"username": "myuser"}''
```

Response example:
```json
{
"data": "dev tun\nproto udp\..\ncompress\n"
}
```

Throws a validation error if the user is not found.

### download-user-2fa

Download the 2FA secret, the secret is encoded inside a QR code in a SVG file:
```
api-cli ns.ovpnrw download-user-2fa --data '{"username": "myuser"}''
```

Response example:
```json
{
"data": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<!-- Created with qrencode 4.1.1 (https://fukuchi.org/works/qrencode/index.html) -->\n<svg width=\"4.34cm\..."
}
```

Throws a validation error if the user is not found.

## ns.dedalo

Manage Dedalo hotspot
Expand Down
Loading

0 comments on commit 5e42e33

Please sign in to comment.