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. For more information on applicable environment variables see The libcurl documentation.

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}