Skip to content

Commit 1c6b1fe

Browse files
JTorreGJTorreG
authored
Merge pull request #161 from nginx/unitctl-docs
docs: add CLI doc
2 parents 2c816c0 + 23a127d commit 1c6b1fe

File tree

2 files changed

+390
-0
lines changed

2 files changed

+390
-0
lines changed

‎source/contents.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
scripting
1111
certificates
1212
statusapi
13+
unitctl
1314
howto/index
1415
troubleshooting
1516
community

‎source/unitctl.rst

Lines changed: 389 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,389 @@
1+
.. meta::
2+
:og:description: Learn how to use the Unit CLI.
3+
4+
.. include:: include/replace.rst
5+
6+
#############
7+
CLI (unitctl)
8+
#############
9+
10+
Unit provides a `Rust SDK <https://github.com/nginx/unit/tree/master/tools/unitctl>`_
11+
to interact with its :ref:`control API <source-startup>`, and a command line
12+
interface (unitctl) that exposes the functionality provided by the SDK.
13+
14+
This CLI is a powerful tool that allows you to deploy, manage, and configure
15+
Unit in your environment.
16+
17+
*****************
18+
Download binaries
19+
*****************
20+
21+
Unitctl binaries are available for Linux (ARM64 and X64) and macOS systems.
22+
23+
Download the latest binaries from the `Unit GitHub releases page
24+
<https://github.com/nginx/unit/releases>`_.
25+
26+
*****************
27+
Build from source
28+
*****************
29+
30+
To build unitctl from source, follow the instructions in the `unitctl repository
31+
<https://github.com/nginx/unit/tree/master/tools/unitctl>`_.
32+
33+
*************
34+
Using unitctl
35+
*************
36+
37+
The unitctl CLI offers several commands to interact with Unit. Here are the available commands:
38+
39+
.. list-table::
40+
:header-rows: 1
41+
42+
* - Command
43+
- Description
44+
45+
* - **instances**
46+
- List all running Unit processes
47+
48+
* - **app**
49+
- List and restart active applications
50+
51+
* - **edit**
52+
- Open the current Unit configuration in the default system editor
53+
54+
* - **export**
55+
- Export the current Unit configuration (excluding certificates) to a
56+
tarball
57+
58+
* - **import**
59+
- Import Unit configuration from a directory
60+
61+
* - **execute**
62+
- Send a raw JSON payload to Unit
63+
64+
* - **status**
65+
- Get the current status of Unit
66+
67+
* - **listeners**
68+
- List all active listeners
69+
70+
* - **help**
71+
- Display help information for commands and options
72+
73+
There are also a number of options that you can use with the unitctl CLI:
74+
75+
.. list-table::
76+
:header-rows: 1
77+
78+
* - Option
79+
- Description
80+
81+
* - **-s, --control-socket-address <CONTROL_SOCKET_ADDRESS>**
82+
- Specify a path (unix:/var/run/unit/control.sock), TCP addres with port
83+
(127.0.0.1:80), or URL for Unit's control socket
84+
85+
* - **-w, --wait-timeout-seconds <WAIT_TIMEOUT_SECONDS>**
86+
- Specify the timeout in seconds for the control socket to become available
87+
88+
* - **-t, --wait-max-tries <WAIT_MAX_TRIES>**
89+
- Specify the maximum number of tries to connect to the control socket when
90+
waiting (default: 3)
91+
92+
* - **-h, --help**
93+
- Display help information for commands and options
94+
95+
* - **-v, --version**
96+
- Display the version of the unitctl CLI
97+
98+
+++++++++++++++++++++++++++++++++
99+
List and create instances of Unit
100+
+++++++++++++++++++++++++++++++++
101+
102+
The **instances** command lets you list all running Unit processes and
103+
deploy new instances of Unit.
104+
105+
The **instances** command has the following option:
106+
107+
.. list-table::
108+
:header-rows: 1
109+
110+
* - Option
111+
- Description
112+
113+
* - **new**
114+
- Deploy a new instance of Unit
115+
116+
Running unitcl with the **instances** command shows output similar to this:
117+
118+
.. code-block:: console
119+
120+
$ unitctl instances
121+
No socket path provided - attempting to detect from running instance
122+
unitd instance [pid: 79489, version: 1.32.0]:
123+
Executable: /opt/unit/sbin/unitd
124+
API control unix socket: unix:/opt/unit/control.unit.sock
125+
Child processes ids: 79489, 79489
126+
Runtime flags: --no-daemon
127+
Configure options: --prefix=/opt/unit --user=myUser --group=myGroup --openssl
128+
129+
You can use the **new** option with three arguments to deploy a new instance of Unit:
130+
131+
1. **Control API path**: A file path for a Unix socket or a TCP address with port.
132+
133+
- If you specify a directory, the Unit container will mount it to **/var/run** internally.
134+
The control socket and pid file are accessible from the host. Example: **/tmp/2**.
135+
- If you specify a TCP address, the Unit container will listen on this
136+
address and port. Example: **127.0.0.1:7171**.
137+
138+
2. **Application path**. The Unit container will mount this path in read-only mode
139+
to **/www** internally. This setup allows you to configure the Unit
140+
container to expose an application stored on the host. Example: **$(pwd)**.
141+
142+
3. **Image tag**: Unitctl will deploy this image, enabling you use custom
143+
images. For example: **unit:wasm**.
144+
145+
.. code-block:: console
146+
147+
$ unitctl instances new /tmp/2 $(pwd) 'unit:wasm'
148+
Pulling and starting a container from unit:wasm
149+
Will mount /tmp/2 to /var/run for socket access
150+
Will READ ONLY mount /home/user/unitctl to /www for application access
151+
Note: Container will be on host network
152+
153+
After the deployment is complete, you will have one Unit container running on the
154+
host network.
155+
156+
+++++++++++++++++++++++++++++
157+
List and restart running apps
158+
+++++++++++++++++++++++++++++
159+
160+
The **app** command lets you list and restart active applications.
161+
162+
Options
163+
-------
164+
165+
The **app** command has the following options:
166+
167+
.. list-table::
168+
:header-rows: 1
169+
170+
* - Option
171+
- Description
172+
173+
* - **list**
174+
- List all active applications
175+
176+
* - **reload <APP_NAME>**
177+
- Restart the specified application
178+
179+
To list active applications, run:
180+
181+
.. code-block:: console
182+
183+
$ unitctl app list
184+
{
185+
"wasm": {
186+
"type": "wasm-wasi-component",
187+
"component": "/www/wasmapp-proxy-component.wasm"
188+
}
189+
}
190+
191+
To restart an application, run:
192+
193+
.. code-block:: console
194+
195+
$ unitctl app reload wasm
196+
{
197+
"success": "Ok"
198+
}
199+
200+
.. note::
201+
202+
This command supports operating on multiple instances of Unit at once. To do
203+
this, use the **-s** option multiple times with different values:
204+
205+
.. code-block:: console
206+
207+
$ unitctl -s '127.0.0.1:8001' -s /run/nginx-unit.control.sock app list
208+
209+
++++++++++++++++++++++
210+
Fetch active listeners
211+
++++++++++++++++++++++
212+
213+
Unitctl can query a given control API to fetch all configured listeners.
214+
215+
To list all active listeners, run:
216+
217+
.. code-block:: console
218+
219+
$ unitctl listeners
220+
No socket path provided - attempting to detect from running instance
221+
{
222+
"127.0.0.1:8080": {
223+
"pass": "routes"
224+
}
225+
}
226+
227+
.. note::
228+
229+
This command supports operating on multiple instances of Unit at once. To do
230+
this, use the **-s** option multiple times with different values:
231+
232+
.. code-block:: console
233+
234+
$ unitctl -s '127.0.0.1:8001' -s /run/nginx-unit.control.sock listeners
235+
236+
++++++++++++++++++++++++
237+
Check the status of Unit
238+
++++++++++++++++++++++++
239+
240+
Unitctl can query the control API to provide the **status** of the running Unit
241+
daemon.
242+
243+
To get the current status of the Unit, run:
244+
245+
.. code-block:: console
246+
247+
$ unitctl status -t yaml
248+
No socket path provided - attempting to detect from running instance
249+
connections:
250+
accepted: 0
251+
active: 0
252+
idle: 0
253+
closed: 0
254+
requests:
255+
total: 0
256+
applications: {}
257+
258+
.. note::
259+
260+
This command supports operating on multiple instances of Unit at once. To do
261+
this, use the **-s** option multiple times with different values:
262+
263+
.. code-block:: console
264+
265+
$ unitctl -s '127.0.0.1:8001' -s /run/nginx-unit.control.sock status
266+
267+
+++++++++++++++++++++++++++++++++++
268+
Send configuration payloads to Unit
269+
+++++++++++++++++++++++++++++++++++
270+
271+
With the **execute** command, Unitctl can accept custom request payloads and
272+
query specified API endpoints with them. Use the **-f** flag to pass the request
273+
payload as a filename or **-** to denote stdin, as shown in the example below.
274+
275+
.. code-block:: console
276+
277+
$ echo '{
278+
"listeners": {
279+
"127.0.0.1:8080": {
280+
"pass": "routes"
281+
}
282+
},
283+
284+
"routes": [
285+
{
286+
"action": {
287+
"share": "/www/data$uri"
288+
}
289+
}
290+
]
291+
}' | unitctl execute --http-method PUT --path /config -f -
292+
{
293+
"success": "Reconfiguration done."
294+
}
295+
296+
.. note::
297+
298+
This command supports operating on multiple instances of Unit at once. To do
299+
this, use the **-s** option multiple times with different values:
300+
301+
.. code-block:: console
302+
303+
$ unitctl -s '127.0.0.1:8001' -s /run/nginx-unit.control.sock execute ...
304+
305+
++++++++++++++++++++++++++
306+
Edit current configuration
307+
++++++++++++++++++++++++++
308+
309+
Unitctl can fetch the configuration from a running instance of Unit and load it
310+
in a preconfigured editor on your command line using the **edit** command.
311+
312+
Unitctl tries to use the editor configured with the **EDITOR** environment
313+
variable, but defaults to vim, emacs, nano, vi, or pico if **EDITOR** is not set.
314+
315+
To edit the current configuration, run:
316+
317+
.. code-block:: console
318+
319+
$ unitctl edit
320+
321+
The configuration loads into the editor, allowing you to make any necessary
322+
changes. Once you save and close the editor, you see the following output:
323+
324+
.. code-block:: console
325+
326+
{
327+
"success": "Reconfiguration done."
328+
}
329+
330+
.. note::
331+
332+
This command does not support operating on multiple instances of Unit at once.
333+
334+
+++++++++++++++++++++++++++++++++++++++++
335+
Importing the configuration from a folder
336+
+++++++++++++++++++++++++++++++++++++++++
337+
338+
The **import** command lets Unitctl read configuration files, certificates, and
339+
NJS modules from a directory. Unitctl then converts these files into a payload
340+
to reconfigure a Unit daemon.
341+
342+
To export the configuration, run:
343+
344+
.. code-block:: console
345+
346+
$ unitctl import /opt/unit/config
347+
Imported /opt/unit/config/certificates/snake.pem -> /certificates/snake.pem
348+
Imported /opt/unit/config/hello.js -> /js_modules/hello.js
349+
Imported /opt/unit/config/put.json -> /config
350+
Imported 3 files
351+
352+
+++++++++++++++++++++++++++++++++++++
353+
Exporting the configuration from Unit
354+
+++++++++++++++++++++++++++++++++++++
355+
356+
The **export** command queries a control API to fetch the running configuration
357+
and NJS modules from a Unit process. The output does not include the currently
358+
stored certificate bundles due to a technical limitation. The output is saved
359+
as a tarball with the filename specified by the **-f** argument. You can also
360+
use standard output with **-f -**, as shown in the examples below:
361+
362+
.. code-block:: console
363+
364+
$ unitctl export -f config.tar
365+
$ unitctl export -f -
366+
$ unitctl export -f - | tar xf - config.json
367+
$ unitctl export -f - > config.tar
368+
369+
.. warning::
370+
371+
The exported configuration omits certificates.
372+
373+
.. note::
374+
375+
This command does not support operating on multiple instances of Unit at once.
376+
377+
+++++++++++++++++++++++++++++++++
378+
Wait for a socket to be available
379+
+++++++++++++++++++++++++++++++++
380+
381+
All commands support waiting for Unix sockets to become available:
382+
383+
.. code-block:: console
384+
385+
$ unitctl --wait-timeout-seconds=3 --wait-max-tries=4 import /opt/unit/config`
386+
Waiting for 3s control socket to be available try 2/4...
387+
Waiting for 3s control socket to be available try 3/4...
388+
Waiting for 3s control socket to be available try 4/4...
389+
Timeout waiting for unit to start has been exceeded

0 commit comments

Comments
 (0)