Skip to content

Commit

Permalink
README: remove old doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@gsanchietti
gsanchietti committed Mar 11, 2024
1 parent c477dcb commit 42e2c8c
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 172 deletions.
165 changes: 1 addition & 164 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,170 +101,7 @@ Unauthenticated APIs:
- `/register`: invoked by firewalls to register themselves, this API should be always invoked using a valid HTTPS endpoint to
ensure the identity of the server

### /login - POST

Execute the login and return `access_token` and `refresh_token`.

Example:
```
curl -H 'Content-Type: application/json' -X POST http://localhost:8080/api/login --data '{"username": "admin", "password": "admin"}'
```

Response:
```json
{
"access_token": "eyJ0xxxxxxxxxxxxxxxxxxxxxxxx",
"refresh_token": "ererexxxxxxxxxxxxxxxxxxxxxxxx",
}
```

### /refresh - POST

Refresh the access token.
This API is authenticated using the `refresh_token`.

Example:
```
curl -H 'Content-Type: application/json' -X POST -H 'Authorization: Bearer <refresh_token>' http://localhost:8080/api/refresh
```

Response:
```json
{
"access_token": "eyJ0xxxxxxxxxxxxxxxxxxxxxxxx",
}
```

### /logout - POST

Execute the logout by putting the token inside the internal blacklist.
This API is authenticated using the `refresh_token`.

Example:
```
curl -H 'Content-Type: application/json' -X POST -H 'Authorization: Bearer <refresh_token>' http://localhost:8080/api/logout
```

Response:
```json
{"msg":"Access token revoked"}
```


### /servers - GET

List existing servers (firewalls).
If the `registered` flag is false, the firewall is in waiting list.

This API is authenticated using the `access_token`.

Example:
```
curl -H 'Content-Type: application/json' -H 'Authorization: Bearer <access_token>' http://localhost:8080/api/servers
```

Response:
```json
[
{
"ipaddress": "172.21.0.2",
"name": "fw1",
"netmask": "255.255.0.0",
"registered": true,
"vpn": {
"bytes_rcvd": "3383",
"bytes_sent": "3077",
"connected_since": "1653383230",
"real_address": "192.168.122.40:46099",
"virtual_address": "172.21.0.2"
}
},
{
"ipaddress": "",
"name": "fw2",
"netmask": "",
"registered": false,
"vpn": null
}
]
```

### /servers - POST

Add a new server to the VPN and proxy configuration.
It also reserves a new IP address.

Example:
```
curl -H 'Content-Type: application/json' -H 'Authorization: Bearer <access_token>' -X POST http://localhost:8080/api/servers --data '{"name": "fw1"}'
```

Response:
```json
{"ipaddress": "172.21.0.2"}
```

This will create a file inside `/etc/openvpn/ccd/<client_name>` containing:
```
ifconfig-push 172.21.0.2 255.255.0.0
```

If the file named `/etc/openvpn/ccd/<client_name>` doesn't exists, the client authentication will fail.

### /servers/_name_ - DELETE

Delete an existing server.

This API is authenticated using the `access_token`.

Example:
```
curl -H 'Content-Type: application/json' -H 'Authorization: Bearer <access_token>' -X DELETE http://localhost:8080/api/servers/delete/fw1
```

### /servers/token - POST

Login to server Luci instance and return the token.
The token can be then used to execute API calls directly to Luci.

This API is authenticated using the `access_token`.

Example:
```
curl -H 'Content-Type: application/json' -X POST -H 'Authorization: Bearer <access_token>' http://localhost:8080/api/servers/token --data '{"name": "fw1"}'
```

Response:
```
{"token": "xxxxxxxxxxx"}
```

### /servers/register - POST

This API is invoked by firewall to register themselves to the controller.
This API is *not* authenticated.

If the firewall is already registered, the server will check for `system_id` and `username`;
if they match, the password will be updated and the VPN configuration returned to firewall.

If the firewall is not registered, it will be added to the waiting list and the server will return a 403 HTTP error code.
The firewall can continue to poll the same endpoint until the admin approves the systemd_id inside the waiting list.

Example:
```
curl http://localhost:8080/api/servers/register -X POST --data '{"system_id": "12345", "username": "random_user", "password": "random_password"}
```

Response:
```json
{
"ca": "-----BEGIN CERTIFICATE-----\nMIIiUwbffWYrN\nfs....tkItNbKbA==\n-----END CERTIFICATE-----\n",
"cert": "Certificate.......-----BEGIN CERTIFICATE-----\nMIIDSz....==\n-----END CERTIFICATE-----\n",
"host": "controller.nethserver.org",
"key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBg....kqj...ernr0M=\n-----END PRIVATE KEY-----\n",
"port": 1194
}
```
See the [API documentation](api/README.md) for more details.

## Build

Expand Down
19 changes: 11 additions & 8 deletions api/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,8 @@ CGO_ENABLED=0 go build
"data": [
{
"ipaddress": "172.23.21.3",
"name": "<unit_name>",
"id": "<unit_id>",
"name": "fw.nethsecurity.local",
"netmask": "255.255.255.0",
"registered": true,
"vpn": {
Expand All @@ -134,7 +135,7 @@ CGO_ENABLED=0 go build
...
{
"ipaddress": "",
"name": "<unit_name>",
"id": "<unit_name>",
"netmask": "",
"registered": false,
"vpn": {}
Expand All @@ -143,7 +144,7 @@ CGO_ENABLED=0 go build
"message": "units listed successfully"
}
```
- `GET /units/<unit_name>`
- `GET /units/<unit_id>`

REQ
```json
Expand All @@ -160,7 +161,8 @@ CGO_ENABLED=0 go build
"code": 200,
"data": {
"ipaddress": "172.23.21.3",
"name": "<unit_name>",
"id": "<unit_id>",
"name": "fw.nethsecurity.local",
"netmask": "255.255.255.0",
"registered": true,
"vpn": {
Expand All @@ -174,7 +176,7 @@ CGO_ENABLED=0 go build
"message": "unit listed successfully"
}
```
- `GET /units/<unit_name>/token`
- `GET /units/<unit_id>/token`

REQ
```json
Expand Down Expand Up @@ -204,7 +206,7 @@ CGO_ENABLED=0 go build
Authorization: Bearer <JWT_TOKEN>

{
"unit_name": "<unit_name>"
"unit_id": "<unit_id>"
}
```

Expand All @@ -229,7 +231,8 @@ CGO_ENABLED=0 go build
Authorization: Bearer <JWT_TOKEN>

{
"unit_name": "<unit_name>",
"unit_name": "fw.nethsecurity.local",
"unit_id": "d330b2db-cdfe-4c56-b9b6-f97e5b838748",
"username": "test",
"password": "Nethesis,1234"
}
Expand Down Expand Up @@ -266,7 +269,7 @@ CGO_ENABLED=0 go build
"message": "unit added to waiting list"
}
```
- `DELETE /units/<unit_name>`
- `DELETE /units/<unit_id>`

REQ
```json
Expand Down

0 comments on commit 42e2c8c

Please sign in to comment.