205 lines
No EOL
6.4 KiB
Markdown
205 lines
No EOL
6.4 KiB
Markdown
# Unitctl
|
|
A command line utility for the access and control of running instances of NGINX Unit.
|
|
|
|
## Building
|
|
First build with `cargo build`. Then copy `target/debug/unitctl` to wherever it is needed.
|
|
|
|
Example:
|
|
```
|
|
λ cargo build
|
|
...
|
|
λ ln -s $(pwd)/target/debug/unitctl $HOME/bin
|
|
λ unitctl
|
|
|
|
Usage: unitctl <COMMAND>
|
|
|
|
Commands:
|
|
start
|
|
status
|
|
api
|
|
schema
|
|
help Print this message or the help of the given subcommand(s)
|
|
|
|
Options:
|
|
-h, --help Print help
|
|
-V, --version Print version
|
|
```
|
|
|
|
## Usage
|
|
Unitctl has many functions.
|
|
- It can start and mount a Unit container for your development environment.
|
|
- It can make queries to a Unit control API.
|
|
- It can print out the schema definition of an endpoint from the Unit control API.
|
|
- It can help list out the endpoints you may need to query from the control API.
|
|
|
|
### Starting a running Unit instance
|
|
```
|
|
λ target/debug/unitctl start
|
|
|
|
Usage: unitctl start --socket <SOCKET>
|
|
|
|
Options:
|
|
-s, --socket <SOCKET> path to desired control socket
|
|
-h, --help Print help
|
|
```
|
|
|
|
Unitctl will load and start a local Unit container.
|
|
When the container starts it will be on the host network.
|
|
The current directory will be mounted to `/www` in the container.
|
|
The user will have to specify a directory to mount the Unit control socket to.
|
|
Whatever directory is specified will be mounted to `/var/run` in the Unit container.
|
|
|
|
Example:
|
|
```
|
|
λ target/debug/unitctl start -s /tmp
|
|
|
|
Using default tag: latest
|
|
latest: Pulling from library/unit
|
|
Digest: sha256:bae510e7594ba1a68895859cc7fa79ed4231907820d46c4a859f5cbe25f85a7e
|
|
Status: Image is up to date for unit:latest
|
|
docker.io/library/unit:latest
|
|
e22783542fabc49a120edc84fc3a48830b8fec0bda16ab20ed0fac95c743486b
|
|
Congratulations! NGINX Unit now running at /tmp/control.unit.sock
|
|
NOTICE: Socket access is root only by default. Run chown.
|
|
Current directory mounted to /www in NGINX Unit container.
|
|
```
|
|
|
|
### Working with the Unit API
|
|
```
|
|
λ unitctl api
|
|
|
|
Usage: unitctl api [OPTIONS] --uri <URI>
|
|
|
|
Options:
|
|
-u, --uri <URI> URI for API operation
|
|
-s, --socket <SOCKET> Unix Socket the control API listens on
|
|
-j, --json <JSON> inline JSON data to post to API
|
|
-f, --file <FILE> file containing data to post to API.
|
|
-d, --delete switch to trigger a delete operation on an API endpoint.
|
|
-v, --verbose switch to trigger verbose behavior in libcurl
|
|
-h, --help Print help
|
|
```
|
|
|
|
Unitctl can act as an API client for the Unit Control API.
|
|
A user will need to specify a URL to connect to, with the API endpoint specified as well.
|
|
Use of the `json` or `file` flags will result in a put request being made.
|
|
The Delete flag can be used to send a delete request.
|
|
|
|
Optionally, a user can specify a unix domain socket filepath with the `socket` flag.
|
|
When this flag is specified the user should continue to prepend their URIs with `http://localhost`.
|
|
|
|
Example:
|
|
```
|
|
λ target/debug/unitctl api -s /tmp/control.unit.sock -u 'http://localhost/config' -v
|
|
|
|
* Trying /tmp/control.unit.sock:0...
|
|
* Connected to localhost (/tmp/control.unit.sock) port 0
|
|
> GET /config HTTP/1.1
|
|
Host: localhost
|
|
Accept: */*
|
|
|
|
* Request completely sent off
|
|
< HTTP/1.1 200 OK
|
|
< Server: Unit/1.32.1
|
|
< Date: Tue, 16 Apr 2024 00:34:31 GMT
|
|
< Content-Type: application/json
|
|
< Content-Length: 335
|
|
< Connection: close
|
|
<
|
|
{ {
|
|
"listeners": {
|
|
"*:80": {
|
|
"pass": "routes"
|
|
}
|
|
},
|
|
|
|
"routes": [
|
|
{
|
|
"match": {
|
|
"headers": {
|
|
"accept": "*text/html*"
|
|
}
|
|
},
|
|
|
|
"action": {
|
|
"share": "/usr/share/unit/welcome/welcome.html"
|
|
}
|
|
},
|
|
{
|
|
"action": {
|
|
"share": "/usr/share/unit/welcome/welcome.md"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
* Closing connection
|
|
```
|
|
|
|
Additional customization can be done with the User's `~/.netrc` file or with libcurl environment variables.
|
|
For more information on `.netrc` see
|
|
[The Curl project's .netrc documentation](https://everything.curl.dev/usingcurl/netrc.html).
|
|
For more information on applicable environment variables see
|
|
[The libcurl documentation](https://curl.se/libcurl/c/libcurl-env.html).
|
|
|
|
### Querying the Unit Control API schema
|
|
```
|
|
λ unitctl schema
|
|
|
|
Usage: unitctl schema [OPTIONS] --path <PATH>
|
|
|
|
Options:
|
|
-p, --path <PATH> path for schema query
|
|
-s, --search set this flag to search for endpoints that match a prefix
|
|
-h, --help Print help
|
|
\
|
|
```
|
|
|
|
Unitctl can act as a schema browser for the Unit Control API as well.
|
|
The user may either specify path to dump schema per endpoint, or may also add the `search` flag
|
|
to search for endpoints prefixed by the given path fragment.
|
|
|
|
Example of an API endpoint schema:
|
|
```
|
|
λ target/debug/unitctl schema -p /status/connections/idle
|
|
|
|
---
|
|
summary: "Endpoint for the `idle` connections number"
|
|
get:
|
|
operationId: getStatusConnectionsIdle
|
|
summary: Retrieve the idle connections number
|
|
description: "Retrieves the `idle` connections number that represents Unit's [connection statistics](https://unit.nginx.org/usagestats/)."
|
|
tags:
|
|
- status
|
|
responses:
|
|
"200":
|
|
description: "OK; the `idle` number exists in the configuration."
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: integer
|
|
examples:
|
|
Idle:
|
|
value: 4
|
|
```
|
|
|
|
Example of a search for endpoints:
|
|
```
|
|
λ unitctl schema --search --path /config/lis
|
|
|
|
- /config/listeners
|
|
- /config/listeners/{listenerName}
|
|
- /config/listeners/{listenerName}/pass
|
|
- /config/listeners/{listenerName}/tls
|
|
- /config/listeners/{listenerName}/tls/conf_commands
|
|
- /config/listeners/{listenerName}/tls/session
|
|
- /config/listeners/{listenerName}/tls/session/tickets
|
|
- /config/listeners/{listenerName}/tls/session/tickets/{arrayIndex}
|
|
- /config/listeners/{listenerName}/tls/certificate
|
|
- /config/listeners/{listenerName}/tls/certificate/{arrayIndex}
|
|
- /config/listeners/{listenerName}/forwarded
|
|
- /config/listeners/{listenerName}/forwarded/client_ip
|
|
- /config/listeners/{listenerName}/forwarded/protocol
|
|
- /config/listeners/{listenerName}/forwarded/recursive
|
|
- /config/listeners/{listenerName}/forwarded/source
|
|
- /config/listeners/{listenerName}/forwarded/source/{arrayIndex}
|
|
``` |