List and create instances of Unit§

The instances command lets you list all running Unit processes and deploy new instances of Unit.

The instances command has the following option:

Running unitcl with the instances command shows output similar to this:

$ unitctl instances
No socket path provided - attempting to detect from running instance
unitd instance [pid: 79489, version: 1.32.0]:
   Executable: /opt/unit/sbin/unitd
   API control unix socket: unix:/opt/unit/control.unit.sock
   Child processes ids: 79489, 79489
   Runtime flags: --no-daemon
   Configure options: --prefix=/opt/unit --user=myUser --group=myGroup --openssl

You can use the new option with three arguments to deploy a new instance of Unit:

1. Control API path: A file path for a Unix socket or a TCP address with port.
   • If you specify a directory, the Unit container will mount it to /var/run internally. The control socket and pid file are accessible from the host. Example: /tmp/2.
   • If you specify a TCP address, the Unit container will listen on this address and port. Example: 127.0.0.1:7171.
2. Application path. The Unit container will mount this path in read-only mode to /www internally. This setup allows you to configure the Unit container to expose an application stored on the host. Example: $(pwd).
3. Image tag: Unitctl will deploy this image, enabling you use custom images. For example: unit:wasm.

$ unitctl instances new /tmp/2 $(pwd) 'unit:wasm'
Pulling and starting a container from unit:wasm
Will mount /tmp/2 to /var/run for socket access
Will READ ONLY mount /home/user/unitctl to /www for application access
Note: Container will be on host network

After the deployment is complete, you will have one Unit container running on the host network.

List and restart running apps§

The apps command lets you list and restart active applications.

$ unitctl apps list
{
  "wasm": {
     "type": "wasm-wasi-component",
     "component": "/www/wasmapp-proxy-component.wasm"
  }
}

$ unitctl apps restart wasm
{
   "success": "Ok"
}

$ unitctl -s '127.0.0.1:8001' -s /run/nginx-unit.control.sock app list

Fetch active listeners§

Unitctl can query a given control API to fetch all configured listeners.

To list all active listeners, run:

$ unitctl listeners
No socket path provided - attempting to detect from running instance
{
   "127.0.0.1:8080": {
      "pass": "routes"
   }
}

$ unitctl -s '127.0.0.1:8001' -s /run/nginx-unit.control.sock listeners

Check the status of Unit§

Unitctl can query the control API to provide the status of the running Unit daemon.

To get the current status of the Unit, run:

$ unitctl status -t yaml
No socket path provided - attempting to detect from running instance
connections:
   accepted: 0
   active: 0
   idle: 0
   closed: 0
requests:
   total: 0
applications: {}

$ unitctl -s '127.0.0.1:8001' -s /run/nginx-unit.control.sock status

Send configuration payloads to Unit§

With the execute command, Unitctl can accept custom request payloads and query specified API endpoints with them. Use the -f flag to pass the request payload as a filename or - to denote stdin, as shown in the example below.

$ echo '{
   "listeners": {
      "127.0.0.1:8080": {
            "pass": "routes"
      }
   },

   "routes": [
      {
            "action": {
               "share": "/www/data$uri"
            }
      }
   ]
}' | unitctl execute --http-method PUT --path /config -f -
{
"success": "Reconfiguration done."
}

$ unitctl -s '127.0.0.1:8001' -s /run/nginx-unit.control.sock execute ...

Edit current configuration§

Unitctl can fetch the configuration from a running instance of Unit and load it in a preconfigured editor on your command line using the edit command.

Unitctl tries to use the editor configured with the EDITOR environment variable, but defaults to vim, emacs, nano, vi, or pico if EDITOR is not set.

To edit the current configuration, run:

$ unitctl edit

The configuration loads into the editor, allowing you to make any necessary changes. Once you save and close the editor, you see the following output:

{
"success": "Reconfiguration done."
}

Importing the configuration from a folder§

The import command lets Unitctl read configuration files, certificates, and NJS modules from a directory. Unitctl then converts these files into a payload to reconfigure a Unit daemon.

To export the configuration, run:

$ unitctl import /opt/unit/config
Imported /opt/unit/config/certificates/snake.pem -> /certificates/snake.pem
Imported /opt/unit/config/hello.js -> /js_modules/hello.js
Imported /opt/unit/config/put.json -> /config
Imported 3 files

Exporting the configuration from Unit§

The export command queries a control API to fetch the running configuration and NJS modules from a Unit process. The output does not include the currently stored certificate bundles due to a technical limitation. The output is saved as a tarball with the filename specified by the -f argument. You can also use standard output with -f -, as shown in the examples below:

$ unitctl export -f config.tar

$ unitctl export -f -

$ unitctl export -f - | tar xf - config.json

$ unitctl export -f - > config.tar

Wait for a socket to be available§

All commands support waiting for Unix sockets to become available:

$ unitctl --wait-timeout-seconds=3 --wait-max-tries=4 import /opt/unit/config`
Waiting for 3s control socket to be available try 2/4...
Waiting for 3s control socket to be available try 3/4...
Waiting for 3s control socket to be available try 4/4...
Timeout waiting for unit to start has been exceeded