92 lines
3.2 KiB
Markdown
92 lines
3.2 KiB
Markdown
# Unit Tools
|
|
|
|
This directory contains useful tools for installing, configuring, and
|
|
managing NGINX Unit. They may not be part of official packages and
|
|
should be considered experimental.
|
|
|
|
* [`setup-unit`](#setup-unit)
|
|
* [`unitc`](#unitc)
|
|
|
|
---
|
|
|
|
## setup-unit
|
|
|
|
### A script that simplifies installing and configuring an NGINX Unit server for first-time users
|
|
|
|
* `setup-unit repo-config` configures your package manager with the NGINX
|
|
Unit repository for later installation.
|
|
* `setup-unit welcome` creates an initial configuration to serve a welcome
|
|
web page with NGINX Unit.
|
|
|
|
---
|
|
|
|
## unitc
|
|
|
|
### A curl wrapper for managing NGINX Unit configuration
|
|
|
|
```USAGE: unitc [options] URI```
|
|
|
|
* **URI** specifies the target in Unit's control API, e.g. `/config` .
|
|
* Configuration data is read from stdin.
|
|
* [jq](https://stedolan.github.io/jq/) is used to prettify JSON output, if
|
|
available.
|
|
|
|
| Options | |
|
|
|---------|-|
|
|
| filename … | Read configuration data consequently from the specified files instead of stdin.
|
|
| _HTTP method_ | It is usually not required to specify a HTTP method. `GET` is used to read the configuration. `PUT` is used when making configuration changes unless a specific method is provided.
|
|
| `INSERT` | A _virtual_ HTTP method that prepends data when the URI specifies an existing array. The [jq](https://stedolan.github.io/jq/) tool is required for this option.
|
|
| `-q` \| `--quiet` | No output to stdout.
|
|
|
|
Options are case insensitive and can appear in any order. For example, a
|
|
redundant part of the configuration can be identified by its URI, and
|
|
followed by `delete` in a subsequent command.
|
|
|
|
### Local Configuration
|
|
For local instances of Unit, the control socket is automatically detected.
|
|
The error log is monitored; when changes occur, new log entries are shown.
|
|
|
|
| Options | |
|
|
|---------|-|
|
|
| `-l` \| `--nolog` | Do not monitor the error log after configuration changes.
|
|
|
|
#### Examples
|
|
```shell
|
|
unitc /config
|
|
unitc /control/applications/my_app/restart
|
|
unitc /config < unitconf.json
|
|
echo '{"*:8080": {"pass": "routes"}}' | unitc /config/listeners
|
|
unitc /config/applications/my_app DELETE
|
|
unitc /certificates/bundle cert.pem key.pem
|
|
```
|
|
|
|
### Remote Configuration
|
|
For remote instances of NGINX Unit, the control socket on the remote host can
|
|
be set with the `$UNIT_CTRL` environment variable. The remote control socket
|
|
can be accessed over TCP or SSH, depending on the type of control socket:
|
|
|
|
* `ssh://[user@]remote_host[:ssh_port]/path/to/control.socket`
|
|
* `http://remote_host:unit_control_port`
|
|
|
|
> **Note:** SSH is recommended for remote confguration. Consider the
|
|
> [security implications](https://unit.nginx.org/howto/security/#secure-socket-and-state)
|
|
> of managing remote configuration over plaintext HTTP.
|
|
|
|
| Options | |
|
|
|---------|-|
|
|
| `ssh://…` | Specify the remote Unix control socket on the command line.
|
|
| `http://…`*URI* | For remote TCP control sockets, the URI may include the protocol, hostname, and port.
|
|
|
|
#### Examples
|
|
```shell
|
|
unitc http://192.168.0.1:8080/status
|
|
UNIT_CTRL=http://192.168.0.1:8080 unitc /status
|
|
|
|
export UNIT_CTRL=ssh://root@unithost/var/run/control.unit.sock
|
|
unitc /config/routes
|
|
cat catchall_route.json | unitc POST /config/routes
|
|
echo '{"match":{"uri":"/wp-admin/*"},"action":{"return":403}}' | unitc INSERT /config/routes
|
|
```
|
|
|
|
---
|