543d478e12
Almost equivalent to b42f6b1d ("Tools: unitc edit mode for interactive
configuration."), implemented by Liam in tools/unitc.
I chose to give preference to vi(1) over vim(1) because Debian has vi(1)
as part of update-alternatives(1), so that sysadmins can configure it to
be a symlink to their favourite vi(1) implementation or variant.
We're ignoring the errors of the commands due to having the SSH tunnel
open. I should fix the script to use traps to close the tunnel on any
error, so we don't leak tunnels. Then, we'll be able to not ignore
curl(1) or editor errors. That will also probably allow moving the
tunneling code to the ctl command, thus deduplicating code.
Cc: Liam Crilly <liam@nginx.com>
Cc: Andrew Clayton <a.clayton@nginx.com>
Signed-off-by: Alejandro Colomar <alx@nginx.com>
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
A script that simplifies installing and configuring an NGINX Unit server for first-time users
setup-unit repo-configconfigures your package manager with the NGINX Unit repository for later installation.setup-unit welcomecreates 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 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. |
edit |
Opens URI in the default editor for interactive configuration. The jq tool is required for this option. |
INSERT |
A virtual HTTP method that prepends data when the URI specifies an existing array. The 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
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.sockethttp://remote_host:unit_control_port
Note: SSH is recommended for remote confguration. Consider the security implications 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
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