# 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
```
λ unitctl start

Usage: unitctl start [OPTIONS] --socket <SOCKET>

Options:
  -s, --socket <SOCKET>  path to desired control socket
  -i, --image <IMAGE>    image tag for the unit container [default: latest]
  -r, --repo <REPO>      alternate docker repository for custom unit images [default: nginx/unit]
  -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}
```