From e57bf56af868b5b1e28555366350cb8f56c8ecf3 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Thu, 1 Aug 2024 16:09:31 +0100 Subject: [PATCH 01/12] docs: add CLI doc draft --- source/contents.rst | 1 + source/unitctl.rst | 359 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 360 insertions(+) create mode 100644 source/unitctl.rst diff --git a/source/contents.rst b/source/contents.rst index e6b8dbea..5cc97b95 100644 --- a/source/contents.rst +++ b/source/contents.rst @@ -10,6 +10,7 @@ scripting certificates statusapi + unitctl howto/index troubleshooting community diff --git a/source/unitctl.rst b/source/unitctl.rst new file mode 100644 index 00000000..5b3ef24f --- /dev/null +++ b/source/unitctl.rst @@ -0,0 +1,359 @@ + .. meta:: + :og:description: Learn how to use the Unit CLI. + +.. include:: include/replace.rst + +############# +CLI (unitctl) +############# + +Unit provides a `Rust SDK `_ +to interact with its :ref:`control API `, and a CLI (unitctl) +that exposes the functionality provided by the SDK. + +This CLI is a powerful tool that allows you to deploy, manage, and configure +Unit in your environment. + +***************** +Download binaries +***************** + +We provide unitctl binaries for Linux (both ARM64 and X64) and MacOS systems. + +.. warning:: + + Links TBD + +***************** +Build from source +***************** + +If you would like to build unitctl from source, you can do so by following the +instructions in the `unitctl repository +`_. + +************* +Using unitctl +************* + +The unitctl CLI provides a number of commands that allow you to interact with +Unit. The following is a list of the available commands: + +.. list-table:: + :header-rows: 1 + + * - Command + - Description + + * - **instances** + - List all running Unit processes + + * - **app** + - List and restart active applications + + * - **edit** + - Open the current Unit configuration in the default system editor + + * - **import** + - Import Unit configuration from a directory + + * - **execute** + - Send a raw JSON payload to Unit + + * - **status** + - Get the current status of the Unit + + * - **listeners** + - List all active listeners + + * - **help** + - Display help information for commands and options + +There are also a number of options that you can use with the unitctl CLI: + +.. list-table:: + :header-rows: 1 + + * - Option + - Description + + * - **-s, --control-socket-address ** + - Specify a path (unix:/var/run/unit/control.sock), TCP addres with port + (127.0.0.1:80), or URL for Unit's control socket + + * - **-w, --wait-timeout-seconds ** + - Specify the timeout in seconds for the control socket to become available + + * - **-t, --wait-max-tries ** + - Specify the maximum number of tries to connect to the control socket when + waiting (default: 3) + + * - **-h, --help** + - Display help information for commands and options + + * - **-v, --version** + - Display the version of the unitctl CLI + ++++++++++++++++++++++++++++++++++ +List and create instances of Unit ++++++++++++++++++++++++++++++++++ + +Running unitcl with the **instances** command will display an output similar to +the following: + +.. code-block:: console + + $ 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 + +The **instances** command can also be used to deploy a new instance of Unit +using the **new** option and three arguments: + +1. A means to show the control API: Either a file path to open a unix socket, or + a TCP address with port. + + - If a directory is specified the Unit container will mount this to + **/var/run** internally. The control socket and pid file will be accessible + from the host. For example: **/tmp/2**. + - If a TCP address is specified, the Unit container will listen on this + address and port. For example: **127.0.0.1:7171**. + +2. A path to an application. The Unit container will mount this in READ ONLY mode + to **/www** internally. This will allow the user to configure their Unit + container to expose an application stored on the host. For example: **$(pwd)**. + +3. An image tag. Unitctl will deploy this image, enabling you to deploy custom + images. For example: **unit:wasm**. + +.. code-block:: console + + $ 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 runnin apps +++++++++++++++++++++++++++++ + +The **app** command allows you to list and restart the active applications. + +To list the active applications, run the following command: + +.. code-block:: console + + $ unitctl app list + { + "wasm": { + "type": "wasm-wasi-component", + "component": "/www/wasmapp-proxy-component.wasm" + } + } + +To restart an application, run the following command: + +.. code-block:: console + + $ unitctl app reload wasm + { + "success": "Ok" + } + +.. note:: + + This command supports operating on multiple instances of Unit at once. To do + this, use the **-s** option multiple times with different values: + + .. code-block:: console + + $ 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 the following command: + +.. code-block:: console + + $ unitctl listeners + No socket path provided - attempting to detect from running instance + { + "127.0.0.1:8080": { + "pass": "routes" + } + } + +.. note:: + + This command supports operating on multiple instances of Unit at once. To do + this, use the **-s** option multiple times with different values: + + .. code-block:: console + + $ 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 the following command: + +.. code-block:: console + + $ 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: {} + +.. note:: + + This command supports operating on multiple instances of Unit at once. To do + this, use the **-s** option multiple times with different values: + + .. code-block:: console + + $ unitctl -s '127.0.0.1:8001' -s /run/nginx-unit.control.sock status + ++++++++++++++++++++++++++++++++++++ +Send configuration payloads to Unit ++++++++++++++++++++++++++++++++++++ + +Unitctl can accept custom request payloads and query given API endpoints with them. +The request payload must be passed in using the **-f** flag either as a filename +or using the **-** filename to denote the use of stdin as shown in the example below. + +.. code-block:: console + + $ 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." + } + +.. note:: + + This command supports operating on multiple instances of Unit at once. To do + this, use the **-s** option multiple times with different values: + + .. code-block:: console + + $ 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 any number of preconfigured editors on your command line. + +Unitctl will try to use whatever editor is configured with the **EDITOR** environment +variable, but will default to vim, emacs, nano, vi, or pico. + +To edit the current configuration, run the following command: + +.. code-block:: console + + $ unitctl edit + +The configuration will be loaded into the editor, and you can make any necessary +changes. Once you save and close the editor, you will see the following output: + +.. code-block:: console + + { + "success": "Reconfiguration done." + } + +.. note:: + + This command does not support operating on multiple instances of Unit at once. + ++++++++++++++++++++++++++++++++++++++++++ +Importing the configuration from a folder ++++++++++++++++++++++++++++++++++++++++++ + +Unitctl will parse existing configuration, certificates, and NJS modules stored +in a directory and convert them into a payload to reconfigure a given Unit daemon. + +To export the configuration, run the following command: + +.. code-block:: console + + $ 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 ++++++++++++++++++++++++++++++++++++++ + +Unitctl will query a control API to fetch running configuration and NJS modules +from a Unit process. Due to a technical limitation this output will not contain +the currently stored certificate bundles. The output is saved as a tarball at the +filename given with the **-f** argument. Standard out may be used with **-f -** +as shown in the following examples: + +.. code-block:: console + + $ unitctl export -f config.tar + $ unitctl export -f - + $ unitctl export -f - | tar xf - config.json + $ unitctl export -f - > config.tar + +.. warning:: + + The exported configuration omits certificates. + +.. note:: + + This command does not support operating on multiple instances of Unit at once. + ++++++++++++++++++++++++++++++++++ +Wait for a socket to be available ++++++++++++++++++++++++++++++++++ + +All commands support waiting on unix sockets for availability: + +.. code-block:: console + + $ 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 \ No newline at end of file From 9c7093fe2d4777987fd6ed5325f2f9a146866bdd Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Tue, 6 Aug 2024 15:34:08 +0100 Subject: [PATCH 02/12] docs: update based on feedback --- source/unitctl.rst | 73 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 54 insertions(+), 19 deletions(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index 5b3ef24f..1eab33f1 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -20,9 +20,8 @@ Download binaries We provide unitctl binaries for Linux (both ARM64 and X64) and MacOS systems. -.. warning:: - - Links TBD +You can find the latest binaries on the `Unit GitHub releases page +`_ ***************** Build from source @@ -54,6 +53,10 @@ Unit. The following is a list of the available commands: * - **edit** - Open the current Unit configuration in the default system editor + * - **export** + - Export the current Unit configuration (excluding certificates) to a + tarball + * - **import** - Import Unit configuration from a directory @@ -98,6 +101,20 @@ There are also a number of options that you can use with the unitctl CLI: List and create instances of Unit +++++++++++++++++++++++++++++++++ +The **instances** command allows you to list all running Unit processes and +deploy new instances of Unit. + +The **instances** command has the following options: + +.. list-table:: + :header-rows: 1 + + * - Option + - Description + + * - **new** + - Deploy a new instance of Unit + Running unitcl with the **instances** command will display an output similar to the following: @@ -142,12 +159,26 @@ using the **new** option and three arguments: After the deployment is complete, you will have one Unit container running on the host network. -++++++++++++++++++++++++++++ -List and restart runnin apps -++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++ +List and restart running apps ++++++++++++++++++++++++++++++ The **app** command allows you to list and restart the active applications. +The **app** command has the following options: + +.. list-table:: + :header-rows: 1 + + * - Option + - Description + + * - **list** + - List all active applications + + * - **reload ** + - Restart the specified application + To list the active applications, run the following command: .. code-block:: console @@ -209,7 +240,8 @@ To list all active listeners, run the following command: Check the status of Unit ++++++++++++++++++++++++ -Unitctl can query the control API to provide the status of the running Unit daemon. +Unitctl can query the control API to provide the **status** of the running Unit +daemon. To get the current status of the Unit, run the following command: @@ -239,9 +271,10 @@ To get the current status of the Unit, run the following command: Send configuration payloads to Unit +++++++++++++++++++++++++++++++++++ -Unitctl can accept custom request payloads and query given API endpoints with them. -The request payload must be passed in using the **-f** flag either as a filename -or using the **-** filename to denote the use of stdin as shown in the example below. +Using the **execute** command, Unitctl can accept custom request payloads and +query given API endpoints with them. The request payload must be passed in using +the **-f** flag either as a filename or using the **-** filename to denote the +use of stdin as shown in the example below. .. code-block:: console @@ -278,7 +311,8 @@ Edit current configuration ++++++++++++++++++++++++++ Unitctl can fetch the configuration from a running instance of Unit and load it -in any number of preconfigured editors on your command line. +in any number of preconfigured editors on your command line using the **edit** +command. Unitctl will try to use whatever editor is configured with the **EDITOR** environment variable, but will default to vim, emacs, nano, vi, or pico. @@ -306,8 +340,9 @@ changes. Once you save and close the editor, you will see the following output: Importing the configuration from a folder +++++++++++++++++++++++++++++++++++++++++ -Unitctl will parse existing configuration, certificates, and NJS modules stored -in a directory and convert them into a payload to reconfigure a given Unit daemon. +Using the **import** command, Unitctl will parse existing configuration, +certificates, and NJS modules stored in a directory and convert them into a +payload to reconfigure a given Unit daemon. To export the configuration, run the following command: @@ -323,11 +358,11 @@ To export the configuration, run the following command: Exporting the configuration from Unit +++++++++++++++++++++++++++++++++++++ -Unitctl will query a control API to fetch running configuration and NJS modules -from a Unit process. Due to a technical limitation this output will not contain -the currently stored certificate bundles. The output is saved as a tarball at the -filename given with the **-f** argument. Standard out may be used with **-f -** -as shown in the following examples: +The **export** command will query a control API to fetch running configuration +and NJS modules from a Unit process. Due to a technical limitation this output +will not contain the currently stored certificate bundles. The output is saved +as a tarball at the filename given with the **-f** argument. Standard out may be +used with **-f -** as shown in the following examples: .. code-block:: console @@ -356,4 +391,4 @@ All commands support waiting on unix sockets for availability: 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 \ No newline at end of file + Timeout waiting for unit to start has been exceeded From 46704bb24e2b16b63ea2d5e8b87ad381f4443bd5 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Tue, 6 Aug 2024 16:13:43 +0100 Subject: [PATCH 03/12] docs: update CLI --- source/unitctl.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index 1eab33f1..0f1fbd79 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -8,8 +8,8 @@ CLI (unitctl) ############# Unit provides a `Rust SDK `_ -to interact with its :ref:`control API `, and a CLI (unitctl) -that exposes the functionality provided by the SDK. +to interact with its :ref:`control API `, and a command line +interface (unitctl) that exposes the functionality provided by the SDK. This CLI is a powerful tool that allows you to deploy, manage, and configure Unit in your environment. From 404516e2894cb3c6254862ecb5c672d2c18b55ae Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Tue, 6 Aug 2024 22:39:28 +0100 Subject: [PATCH 04/12] Apply suggestions from code review Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- source/unitctl.rst | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index 0f1fbd79..b2c6f0f8 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -18,25 +18,21 @@ Unit in your environment. Download binaries ***************** -We provide unitctl binaries for Linux (both ARM64 and X64) and MacOS systems. +Unitctl binaries are available for Linux (ARM64 and X64) and MacOS systems. -You can find the latest binaries on the `Unit GitHub releases page -`_ +Download the latest binaries from the `Unit GitHub releases page `_. ***************** Build from source ***************** -If you would like to build unitctl from source, you can do so by following the -instructions in the `unitctl repository -`_. +To build unitctl from source, follow the instructions in the `unitctl repository `_. ************* Using unitctl ************* -The unitctl CLI provides a number of commands that allow you to interact with -Unit. The following is a list of the available commands: +The unitctl CLI offers several commands to interact with Unit. Here are the available commands: .. list-table:: :header-rows: 1 @@ -64,7 +60,7 @@ Unit. The following is a list of the available commands: - Send a raw JSON payload to Unit * - **status** - - Get the current status of the Unit + - Get the current status of Unit * - **listeners** - List all active listeners @@ -101,10 +97,10 @@ There are also a number of options that you can use with the unitctl CLI: List and create instances of Unit +++++++++++++++++++++++++++++++++ -The **instances** command allows you to list all running Unit processes and +The **instances** command lets you list all running Unit processes and deploy new instances of Unit. -The **instances** command has the following options: +The **instances** command has the following option: .. list-table:: :header-rows: 1 @@ -115,8 +111,7 @@ The **instances** command has the following options: * - **new** - Deploy a new instance of Unit -Running unitcl with the **instances** command will display an output similar to -the following: +Running unitcl with the **instances** command shows output similar to this: .. code-block:: console @@ -129,8 +124,7 @@ the following: Runtime flags: --no-daemon Configure options: --prefix=/opt/unit --user=myUser --group=myGroup --openssl -The **instances** command can also be used to deploy a new instance of Unit -using the **new** option and three arguments: +You can use the **new** option with three arguments to deploy a new instance of Unit: 1. A means to show the control API: Either a file path to open a unix socket, or a TCP address with port. From 3d8cf53d74f5c1a7871dc54bbd9b1c05fa40f749 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Tue, 6 Aug 2024 23:00:23 +0100 Subject: [PATCH 05/12] Apply suggestions from code review Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- source/unitctl.rst | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index b2c6f0f8..93ad55bf 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -126,20 +126,18 @@ Running unitcl with the **instances** command shows output similar to this: You can use the **new** option with three arguments to deploy a new instance of Unit: -1. A means to show the control API: Either a file path to open a unix socket, or - a TCP address with port. +1. **Control API path**: A file path for a Unix socket or a TCP address with port. - - If a directory is specified the Unit container will mount this to - **/var/run** internally. The control socket and pid file will be accessible - from the host. For example: **/tmp/2**. - - If a TCP address is specified, the Unit container will listen on this - address and port. For example: **127.0.0.1:7171**. + - 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. A path to an application. The Unit container will mount this in READ ONLY mode - to **/www** internally. This will allow the user to configure their Unit - container to expose an application stored on the host. For example: **$(pwd)**. +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. An image tag. Unitctl will deploy this image, enabling you to deploy custom +3. **Image tag**: Unitctl will deploy this image, enabling you use custom images. For example: **unit:wasm**. .. code-block:: console From e7169b3363e0d8f5bc4faff536801451a8807d0e Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Tue, 6 Aug 2024 23:04:40 +0100 Subject: [PATCH 06/12] Apply suggestions from code review --- source/unitctl.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index 93ad55bf..ea9ab06d 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -20,13 +20,15 @@ Download binaries Unitctl binaries are available for Linux (ARM64 and X64) and MacOS systems. -Download the latest binaries from the `Unit GitHub releases page `_. +Download the latest binaries from the `Unit GitHub releases page +`_. ***************** Build from source ***************** -To build unitctl from source, follow the instructions in the `unitctl repository `_. +To build unitctl from source, follow the instructions in the `unitctl repository +`_. ************* Using unitctl From 2e40b88b3ea2eb225a65908aaf2c9dae9beb374d Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Wed, 7 Aug 2024 00:02:07 +0100 Subject: [PATCH 07/12] Update source/unitctl.rst --- source/unitctl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index ea9ab06d..5208df51 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -18,7 +18,7 @@ Unit in your environment. Download binaries ***************** -Unitctl binaries are available for Linux (ARM64 and X64) and MacOS systems. +Unitctl binaries are available for Linux (ARM64 and X64) and macOS systems. Download the latest binaries from the `Unit GitHub releases page `_. From c75c10ab1b82dd12f689e8929b7978dd031e43a4 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Wed, 7 Aug 2024 00:02:25 +0100 Subject: [PATCH 08/12] Update source/unitctl.rst Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- source/unitctl.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index 5208df51..00096aea 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -265,10 +265,9 @@ To get the current status of the Unit, run the following command: Send configuration payloads to Unit +++++++++++++++++++++++++++++++++++ -Using the **execute** command, Unitctl can accept custom request payloads and -query given API endpoints with them. The request payload must be passed in using -the **-f** flag either as a filename or using the **-** filename to denote the -use of stdin as shown in the example below. +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. .. code-block:: console From aa1d93257b37f73363d5e99f3e8d5302452a380a Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Wed, 7 Aug 2024 00:02:32 +0100 Subject: [PATCH 09/12] Update source/unitctl.rst Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- source/unitctl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index 00096aea..fccbafab 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -237,7 +237,7 @@ 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 the following command: +To get the current status of the Unit, run: .. code-block:: console From 94f91e3f3c2cf7e37eaa7d234226fbf41dd0e3c6 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Wed, 7 Aug 2024 00:02:37 +0100 Subject: [PATCH 10/12] Update source/unitctl.rst Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- source/unitctl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index fccbafab..1217f9c1 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -209,7 +209,7 @@ Fetch active listeners Unitctl can query a given control API to fetch all configured listeners. -To list all active listeners, run the following command: +To list all active listeners, run: .. code-block:: console From db57049e9986437405266c6dcad4e7d33cc1505b Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Wed, 7 Aug 2024 00:02:48 +0100 Subject: [PATCH 11/12] Update source/unitctl.rst Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- source/unitctl.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index 1217f9c1..92c510c1 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -157,7 +157,10 @@ host network. List and restart running apps +++++++++++++++++++++++++++++ -The **app** command allows you to list and restart the active applications. +The **app** command lets you list and restart active applications. + +Options +------- The **app** command has the following options: @@ -173,7 +176,7 @@ The **app** command has the following options: * - **reload ** - Restart the specified application -To list the active applications, run the following command: +To list active applications, run: .. code-block:: console @@ -185,7 +188,7 @@ To list the active applications, run the following command: } } -To restart an application, run the following command: +To restart an application, run: .. code-block:: console From 23a127d4c605d7c72e1dbe601bee4538b203a703 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Wed, 7 Aug 2024 13:21:27 +0100 Subject: [PATCH 12/12] Apply suggestions from code review Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- source/unitctl.rst | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index 92c510c1..b51c2a90 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -307,20 +307,19 @@ Edit current configuration ++++++++++++++++++++++++++ Unitctl can fetch the configuration from a running instance of Unit and load it -in any number of preconfigured editors on your command line using the **edit** -command. +in a preconfigured editor on your command line using the **edit** command. -Unitctl will try to use whatever editor is configured with the **EDITOR** environment -variable, but will default to vim, emacs, nano, vi, or pico. +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 the following command: +To edit the current configuration, run: .. code-block:: console $ unitctl edit -The configuration will be loaded into the editor, and you can make any necessary -changes. Once you save and close the editor, you will see the following output: +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: .. code-block:: console @@ -336,11 +335,11 @@ changes. Once you save and close the editor, you will see the following output: Importing the configuration from a folder +++++++++++++++++++++++++++++++++++++++++ -Using the **import** command, Unitctl will parse existing configuration, -certificates, and NJS modules stored in a directory and convert them into a -payload to reconfigure a given Unit daemon. +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 the following command: +To export the configuration, run: .. code-block:: console @@ -354,11 +353,11 @@ To export the configuration, run the following command: Exporting the configuration from Unit +++++++++++++++++++++++++++++++++++++ -The **export** command will query a control API to fetch running configuration -and NJS modules from a Unit process. Due to a technical limitation this output -will not contain the currently stored certificate bundles. The output is saved -as a tarball at the filename given with the **-f** argument. Standard out may be -used with **-f -** as shown in the following examples: +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: .. code-block:: console @@ -379,7 +378,7 @@ used with **-f -** as shown in the following examples: Wait for a socket to be available +++++++++++++++++++++++++++++++++ -All commands support waiting on unix sockets for availability: +All commands support waiting for Unix sockets to become available: .. code-block:: console