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/45] 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/45] 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/45] 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/45] 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/45] 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/45] 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/45] 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/45] 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/45] 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/45] 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/45] 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/45] 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 From 8699d5c53c19ed9d2ab16a13d0a08b8f9c091fca Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Tue, 27 Aug 2024 17:40:18 +0100 Subject: [PATCH 13/45] docs: preliminary draft --- source/conf.py | 4 +- source/news/2024/index.rst | 8 ++ source/news/2024/unit-1.33.0-released.rst | 107 ++++++++++++++++++++++ 3 files changed, 117 insertions(+), 2 deletions(-) create mode 100644 source/news/2024/unit-1.33.0-released.rst diff --git a/source/conf.py b/source/conf.py index 8c35115f..236db9c6 100644 --- a/source/conf.py +++ b/source/conf.py @@ -5,8 +5,8 @@ project = 'NGINX Unit' author = 'NGINX, Inc.' copyright = '2017-2024' -version = '1.32.1' -release_date = 'Mar 26, 2024' +version = '1.33.0' +release_date = 'Aug 27, 2024' release = version needs_sphinx = '6.2' diff --git a/source/news/2024/index.rst b/source/news/2024/index.rst index 7019e68f..217505f9 100644 --- a/source/news/2024/index.rst +++ b/source/news/2024/index.rst @@ -4,6 +4,14 @@ News of 2024 News archive for the year 2024. +.. nxt_news_entry:: + :author: Unit Team + :description: Version 1.33.0 + :email: unit-owner@nginx.org + :title: Unit 1.33.0 Released + :url: news/2024/unit-1.33.0-released + :date: 2024-08-29 + .. nxt_news_entry:: :author: Unit Team :description: Version 1.32.1 is a maintenance release that fixes bugs in the new WebAssembly Language Module and in our njs implementation. diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst new file mode 100644 index 00000000..33e58d93 --- /dev/null +++ b/source/news/2024/unit-1.33.0-released.rst @@ -0,0 +1,107 @@ +:orphan: + +#################### +Unit 1.33.0 Released +#################### + + +Unit 1.33.0 is now available. This release includes a number of new features +and changes: + +************************************************************************ +Feature 1 +************************************************************************ + +Feature 1 description. + +******************************************************************* +Feature 2 +******************************************************************* + +Feature 2 description. + +************************************* +Changes in behavior and other updates +************************************* + +========================================================================== +Change 1 +========================================================================== + +Change 1 description. + +======================================================= +Change 2 +======================================================= + +Change 2 description. + +************ +Wall of fame +************ + +Special Thanks to all external contributors helping us +making Unit better! With 1.32.0 we would like to send a shout out to: + +- Alejandro Colomar +- Costas Drongos +- Gourav +- Remi Collet + +Special thanks to Arjun for his fuzzing work. + +************** +Full Changelog +************** + +.. code-block:: none + + Changes with Unit 1.33.0 29 Aug 2024 + + *) Feature: show list of loaded language modules in the /status + endpoint. + + *) Feature: make the number of router threads configurable. + + *) Feature: make the listen(2) backlog configurable. + + *) Feature: add fuzzing via oss-fuzz. + + *) Feature: add Python application factory support. + + *) Feature: add chunked request body support. + + *) Feature: add "if" option to the "match" object. + + *) Feature: Unit ships with a new Rust based CLI application "unitctl". + + *) Change: under systemd unit runs in forking mode (once again). + + *) Change: if building with njs, version 0.8.3 or later is now required. + + *) Change: Unit now builds with -std=gnu11 (C11 with GNU extensions). + + *) Change: Unit now creates the full directory path for the PID file and + control socket. + + *) Change: build system improvements, including pretty printing the make + output and enabling various make variables to influence the build + process (see: make help). + + *) Change: better detection of available runnable CPUs on Linux. + + *) Change: default listen(2) backlog on Linux now defaults to Kernel + default. + + *) Bugfix: don't create the $runstatedir directory which triggered an + Alpine packaging error. + + *) Bugfix: wasm-wasi-component application process hangs after receiving + restart signal from the control endpoint. + + *) Bugfix: njs variables accessed with a JS template literal should not + be cacheable. + + *) Bugfix: don't modify REQUEST_URI. + + *) Bugfix: properly handle deleting arrays of certificates. From 85282d764b6ba8e294b93e44418e790824be424b Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Tue, 27 Aug 2024 19:33:30 +0100 Subject: [PATCH 14/45] Update source/news/2024/unit-1.33.0-released.rst --- source/news/2024/unit-1.33.0-released.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 33e58d93..1cc268e2 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -41,7 +41,7 @@ Wall of fame ************ Special Thanks to all external contributors helping us -making Unit better! With 1.32.0 we would like to send a shout out to: +making Unit better! With 1.33.0 we would like to send a shout out to: - Alejandro Colomar - Costas Drongos From 2c816c04b6706020ba25b22a70c2b2f0f430da3f Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 28 Aug 2024 15:34:17 +0100 Subject: [PATCH 15/45] docs: update doc --- source/news/2024/unit-1.33.0-released.rst | 37 +++++++++++++++++------ 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 1cc268e2..7f842324 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -4,21 +4,38 @@ Unit 1.33.0 Released #################### +We are pleased to announce the release of NGINX Unit 1.33.0. This release includes +a number of new features and changes: -Unit 1.33.0 is now available. This release includes a number of new features -and changes: +************************* +New configuration options +************************* -************************************************************************ -Feature 1 -************************************************************************ +This release introduces two new configuration options: -Feature 1 description. +#. `listen_threads` -******************************************************************* -Feature 2 -******************************************************************* + This option can be set under `/settings/listen_threads` and controls the + number of threads the router process creates to handle client + connections. By default Unit creates the same number of threads as there + are CPUs available. + +#. `backlog` + + This option can be set under `/listeners/backlog`. This is a per-listener + option that sets the the backlog parameter as passed to the listen(2) + system-call, which defines the maximum length for the queue of pending + connections for the socket. + + This is analogous to the `backlog` parameter of the `listen` directive in + NGINX. + +**************** +unitctl CLI tool +**************** + +Chunked request body support -Feature 2 description. ************************************* Changes in behavior and other updates From 1e268930e9bf9af31888f232f9f1997f1f65223c Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 28 Aug 2024 16:55:47 +0100 Subject: [PATCH 16/45] docs: update news --- source/news/2024/unit-1.33.0-released.rst | 103 +++++++++++++++++++--- source/unitctl.rst | 5 +- 2 files changed, 92 insertions(+), 16 deletions(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 7f842324..4899f57f 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -13,45 +13,120 @@ New configuration options This release introduces two new configuration options: -#. `listen_threads` +#. **listen_threads** - This option can be set under `/settings/listen_threads` and controls the + This option can be set under **/settings/listen_threads** and controls the number of threads the router process creates to handle client connections. By default Unit creates the same number of threads as there are CPUs available. -#. `backlog` +#. **backlog** - This option can be set under `/listeners/backlog`. This is a per-listener - option that sets the the backlog parameter as passed to the listen(2) + This option can be set under **/listeners/backlog**. This is a per-listener + option that sets the the backlog parameter as passed to the **listen(2)** system-call, which defines the maximum length for the queue of pending connections for the socket. - This is analogous to the `backlog` parameter of the `listen` directive in + This is analogous to the **backlog** parameter of the **listen** directive in NGINX. **************** unitctl CLI tool **************** +:ref:`unitctl ` is a powerful, Rust-based CLI tool that allows you to +deploy, manage, and configure Unit in your environment. + +**************************** Chunked request body support +**************************** +Unit can now accept chunked requests rather than returning **411 +Length Required**. This feature is experimental and can +be enabled setting the **/settings/chunked_transform** configuration option +to true. ************************************* Changes in behavior and other updates ************************************* -========================================================================== -Change 1 -========================================================================== +* On Linux, we now default to a **listen(2)** backlog of -1, which means we + use the OS's default: 4096 for Linux 5.4 and later; 128 for older versions. + + The previous default for Unit was 511. + +* Under systemd, Unit once again runs in **forking** mode. This allows the + per-application logging feature to work out the box. + +* The Python language module now supports **Application Factories** + (thanks to Gourav). + +********************** +Changes for developers +********************** + +We have made some changes to the build system: + +=============================================== +Prettified make output by default with GNU make +=============================================== + +Instead of getting the normal compiler command for each target being built +you now get a simplified line like: + +.. code-block:: console + + CC build/src/nxt_cgroup.o + + +You can use the `V=1` option to get the old verbose output, for example: + +.. code-block:: console + + make V=1 + +============== +Make variables +============== + +You can now control some aspects of the build process by passing variables to +make (like the above). The currently supported variables are: + +.. list-table:: + :widths: 15 80 5 + :header-rows: 1 + + * - Option + - Description + - Default + * - **D=1** + - Enables debug builds (-O0) + - 0 + * - **E=0** + - Disables -Werror + - 1 + * - **V=1** + - Enables verbose output + - 0 + * - **EXTRA_CFLAGS=** + - Add extra compiler options + - + +=========== +GCC & Clang +=========== + +We removed support for a bunch of esoteric compilers. GCC and Clang are now the +only supported compilers for building Unit. -Change 1 description. +========== +-std=gnu11 +========== -======================================================= -Change 2 -======================================================= +We now build with **-std=gnu11** (C11 with GNU extensions). While previously we +didn't explicitly set the -std= option, as we were supporting CentOS 7 (which is now +EOL), we were effectively limited to **-std=gnu89/90**. -Change 2 description. ************ Wall of fame diff --git a/source/unitctl.rst b/source/unitctl.rst index b51c2a90..86d1b19d 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -2,6 +2,7 @@ :og:description: Learn how to use the Unit CLI. .. include:: include/replace.rst +.. _unitctl: ############# CLI (unitctl) @@ -130,7 +131,7 @@ You can use the **new** option with three arguments to deploy a new instance of 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. + - 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**. @@ -269,7 +270,7 @@ 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 +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 934f65af17d66559199f1c7d3d63c78018b5d581 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 28 Aug 2024 17:04:15 +0100 Subject: [PATCH 17/45] docs: update date --- source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index 236db9c6..b4741340 100644 --- a/source/conf.py +++ b/source/conf.py @@ -6,7 +6,7 @@ author = 'NGINX, Inc.' copyright = '2017-2024' version = '1.33.0' -release_date = 'Aug 27, 2024' +release_date = 'Aug 29, 2024' release = version needs_sphinx = '6.2' From 3180b8f7a12f4d5aa44cb5e7dd6db38737f8babe Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Wed, 28 Aug 2024 17:23:01 +0100 Subject: [PATCH 18/45] Update source/news/2024/unit-1.33.0-released.rst Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- source/news/2024/unit-1.33.0-released.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 4899f57f..0edcfeee 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -17,7 +17,7 @@ This release introduces two new configuration options: This option can be set under **/settings/listen_threads** and controls the number of threads the router process creates to handle client - connections. By default Unit creates the same number of threads as there + connections. By default, Unit creates the same number of threads as there are CPUs available. #. **backlog** From 47faedec5a1b36081ba5e9cf0bd0413960565f3c Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Wed, 28 Aug 2024 17:24:11 +0100 Subject: [PATCH 19/45] Update source/news/2024/unit-1.33.0-released.rst Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- source/news/2024/unit-1.33.0-released.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 0edcfeee..b13faeaf 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -50,8 +50,8 @@ to true. Changes in behavior and other updates ************************************* -* On Linux, we now default to a **listen(2)** backlog of -1, which means we - use the OS's default: 4096 for Linux 5.4 and later; 128 for older versions. +* On Linux, we now default to a **listen(2)** backlog of `-1`, which means we + use the OS's default: `4096` for Linux 5.4 and later; `128` for older versions. The previous default for Unit was 511. From a7fb364802da30de0fb335a3c4bf8868b6fa7ab5 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Wed, 28 Aug 2024 17:25:10 +0100 Subject: [PATCH 20/45] Update source/news/2024/unit-1.33.0-released.rst Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- source/news/2024/unit-1.33.0-released.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index b13faeaf..f49e9dce 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -90,7 +90,7 @@ Make variables ============== You can now control some aspects of the build process by passing variables to -make (like the above). The currently supported variables are: +`make` (like the above). The currently supported variables are: .. list-table:: :widths: 15 80 5 From 1e91444046e43d494dd3ed1f34670866fba7ba8a Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Wed, 28 Aug 2024 17:25:16 +0100 Subject: [PATCH 21/45] Update source/news/2024/unit-1.33.0-released.rst Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- source/news/2024/unit-1.33.0-released.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index f49e9dce..31b17e35 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -116,7 +116,7 @@ You can now control some aspects of the build process by passing variables to GCC & Clang =========== -We removed support for a bunch of esoteric compilers. GCC and Clang are now the +We removed support for a several lesser-known compilers. GCC and Clang are now the only supported compilers for building Unit. ========== From f14d729bd00a953f2323aed5e8d03506b1d9abff Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 28 Aug 2024 17:35:23 +0100 Subject: [PATCH 22/45] docs: fixes --- source/news/2024/unit-1.33.0-released.rst | 2 +- source/unitctl.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 31b17e35..7889e52d 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -34,7 +34,7 @@ This release introduces two new configuration options: unitctl CLI tool **************** -:ref:`unitctl ` is a powerful, Rust-based CLI tool that allows you to +:ref:`unitctl ` is a Rust-based CLI tool that allows you to deploy, manage, and configure Unit in your environment. **************************** diff --git a/source/unitctl.rst b/source/unitctl.rst index 86d1b19d..399ef125 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -12,7 +12,7 @@ Unit provides a `Rust SDK `, 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 +This CLI is a multi-purpose tool that allows you to deploy, manage, and configure Unit in your environment. ***************** From 9229ec789d5d5746fd5eaba88e25bde3c92b447f Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 28 Aug 2024 17:39:13 +0100 Subject: [PATCH 23/45] docs: options in bold --- source/news/2024/unit-1.33.0-released.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 7889e52d..e704cef8 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -50,8 +50,8 @@ to true. Changes in behavior and other updates ************************************* -* On Linux, we now default to a **listen(2)** backlog of `-1`, which means we - use the OS's default: `4096` for Linux 5.4 and later; `128` for older versions. +* On Linux, we now default to a **listen(2)** backlog of **-1**, which means we + use the OS's default: **4096** for Linux 5.4 and later; **128** for older versions. The previous default for Unit was 511. @@ -79,7 +79,7 @@ you now get a simplified line like: CC build/src/nxt_cgroup.o -You can use the `V=1` option to get the old verbose output, for example: +You can use the **V=1** option to get the old verbose output, for example: .. code-block:: console @@ -90,7 +90,7 @@ Make variables ============== You can now control some aspects of the build process by passing variables to -`make` (like the above). The currently supported variables are: +**make** (like the above). The currently supported variables are: .. list-table:: :widths: 15 80 5 From 6d1c2e55768d2d97b39c839b9c7e41b3150fd25d Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 2 Sep 2024 11:23:57 +0100 Subject: [PATCH 24/45] docs: update news desc. --- source/news/2024/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/news/2024/index.rst b/source/news/2024/index.rst index 217505f9..d8f26665 100644 --- a/source/news/2024/index.rst +++ b/source/news/2024/index.rst @@ -6,7 +6,7 @@ News archive for the year 2024. .. nxt_news_entry:: :author: Unit Team - :description: Version 1.33.0 + :description: Version 1.33.0 includes two new configuration options and a CLI tool. :email: unit-owner@nginx.org :title: Unit 1.33.0 Released :url: news/2024/unit-1.33.0-released From 865929e289fdd1f00b2dae83b2ca76218e913c0d Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 2 Sep 2024 11:34:46 +0100 Subject: [PATCH 25/45] docs: remove `a` (regression) --- source/news/2024/unit-1.33.0-released.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index e704cef8..70888eea 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -116,7 +116,7 @@ You can now control some aspects of the build process by passing variables to GCC & Clang =========== -We removed support for a several lesser-known compilers. GCC and Clang are now the +We removed support for several lesser-known compilers. GCC and Clang are now the only supported compilers for building Unit. ========== From b3e25c7f64ecee9c62bec989fa09e6fdc8ee2fa7 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 2 Sep 2024 14:29:55 +0100 Subject: [PATCH 26/45] fix: fix previews --- source/theme/layout.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/theme/layout.html b/source/theme/layout.html index 499ebdc6..c00e6302 100644 --- a/source/theme/layout.html +++ b/source/theme/layout.html @@ -37,7 +37,7 @@ font-style: normal; font-weight: 400; src: local('OpenSans'), local('Open Sans'), local('Open Sans Regular'), local('OpenSans-Regular'), - url('{{ pathto('/_static/open-sans-v40-latin_latin-ext-regular.woff2', 1) + '?' + md5('theme/static/open-sans-v40-latin_latin-ext-regular.woff2') }}') format('woff2'); + url('{{ pathto('_static/open-sans-v40-latin_latin-ext-regular.woff2', 1) + '?' + md5('theme/static/open-sans-v40-latin_latin-ext-regular.woff2') }}') format('woff2'); } /* open-sans-italic - latin_latin-ext */ @@ -47,7 +47,7 @@ font-style: italic; font-weight: 400; src: local('OpenSansItalic'), local('Open Sans Italic'), local('OpenSans Italic'), local('OpenSans-Italic'), - url('{{ pathto('/_static/open-sans-v40-latin_latin-ext-italic.woff2', 1) + '?' + md5('theme/static/open-sans-v40-latin_latin-ext-italic.woff2') }}') format('woff2'); + url('{{ pathto('_static/open-sans-v40-latin_latin-ext-italic.woff2', 1) + '?' + md5('theme/static/open-sans-v40-latin_latin-ext-italic.woff2') }}') format('woff2'); } /* open-sans-700 - latin_latin-ext */ @@ -57,7 +57,7 @@ font-style: normal; font-weight: 700; src: local('OpenSansBold'), local('Open Sans Bold'), local('OpenSans Bold'), local('OpenSans-Bold'), - url('{{ pathto('/_static/open-sans-v40-latin_latin-ext-700.woff2', 1) + '?' + md5('theme/static/open-sans-v40-latin_latin-ext-700.woff2') }}') format('woff2'); + url('{{ pathto('_static/open-sans-v40-latin_latin-ext-700.woff2', 1) + '?' + md5('theme/static/open-sans-v40-latin_latin-ext-700.woff2') }}') format('woff2'); } /* open-sans-700italic - latin_latin-ext */ @@ -67,7 +67,7 @@ font-style: italic; font-weight: 700; src: local('OpenSansBoldItalic'), local('Open Sans Bold Italic'), local('OpenSans Bold Italic'), local('OpenSans-BoldItalic'), local('OpenSans-Bold-Italic'), - url('{{ pathto('/_static/open-sans-v40-latin_latin-ext-700italic.woff2', 1) + '?' + md5('theme/static/open-sans-v40-latin_latin-ext-700italic.woff2') }}') format('woff2'); + url('{{ pathto('_static/open-sans-v40-latin_latin-ext-700italic.woff2', 1) + '?' + md5('theme/static/open-sans-v40-latin_latin-ext-700italic.woff2') }}') format('woff2'); } From f283a0597b45c92b4f18f21330a5dff041c9be1a Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Tue, 3 Sep 2024 18:24:06 +0100 Subject: [PATCH 27/45] fix: fix nav subsections --- .../index.rst} | 108 +++++++++--------- source/contents.rst | 3 +- source/controlapi.rst | 2 +- source/howto/security.rst | 4 +- source/news/2019/unit-1.8.0-released.rst | 2 +- source/scripting.rst | 2 +- 6 files changed, 60 insertions(+), 61 deletions(-) rename source/{configuration.rst => configuration/index.rst} (98%) diff --git a/source/configuration.rst b/source/configuration/index.rst similarity index 98% rename from source/configuration.rst rename to source/configuration/index.rst index 1e71a462..17fa53bb 100644 --- a/source/configuration.rst +++ b/source/configuration/index.rst @@ -2,7 +2,7 @@ :og:description: Create and maintain a working configuration using listeners, routes, apps, and upstreams. -.. include:: include/replace.rst +.. include:: ../include/replace.rst ############# Configuration @@ -2228,7 +2228,7 @@ affects the resulting response headers. The values support :ref:`variables ` and -:doc:`template literals `, +:doc:`template literals <../scripting>`, which enables arbitrary runtime logic: .. code-block:: json @@ -2441,7 +2441,7 @@ A **share**-based action provides the following options: `, the process runs as **unit:unit**; for details of other installation methods, - see :doc:`installation`. + see :doc:`../installation`. Consider the following configuration: @@ -3988,7 +3988,7 @@ and rebuild the app. # yum install unit-devel - If you installed Unit from - :doc:`source `, + :doc:`source <../howto/source>`, install the include files and libraries: .. code-block:: console @@ -4101,7 +4101,7 @@ Example: For Go-based examples, see our - :doc:`howto/grafana` + :doc:`../howto/grafana` howto or a basic :ref:`sample `. @@ -4191,10 +4191,10 @@ Example: For Java-based examples, see our - :doc:`howto/jira`, - :doc:`howto/opengrok`, + :doc:`../howto/jira`, + :doc:`../howto/opengrok`, and - :doc:`howto/springboot` + :doc:`../howto/springboot` howtos or a basic :ref:`sample `. @@ -4343,9 +4343,9 @@ your app only needs to replace the default **websocket**: For Node.js-based examples, see our - :doc:`howto/apollo`, - :doc:`howto/express`, - :doc:`howto/koa`, + :doc:`../howto/apollo`, + :doc:`../howto/express`, + :doc:`../howto/koa`, and :ref:`Docker ` howtos or a basic @@ -4412,9 +4412,9 @@ Example: For Perl-based examples of Perl, see our - :doc:`howto/bugzilla` + :doc:`../howto/bugzilla` and - :doc:`howto/catalyst` + :doc:`../howto/catalyst` howtos or a basic :ref:`sample `. @@ -4665,23 +4665,23 @@ are shared by all targets within the app. For PHP-based examples, see our - :doc:`howto/cakephp`, - :doc:`howto/codeigniter`, - :doc:`howto/dokuwiki`, - :doc:`howto/drupal`, - :doc:`howto/laravel`, - :doc:`howto/lumen`, - :doc:`howto/matomo`, - :doc:`howto/mediawiki`, - :doc:`howto/modx`, - :doc:`howto/nextcloud`, - :doc:`howto/phpbb`, - :doc:`howto/phpmyadmin`, - :doc:`howto/roundcube`, - :doc:`howto/symfony`, - :doc:`howto/wordpress`, + :doc:`../howto/cakephp`, + :doc:`../howto/codeigniter`, + :doc:`../howto/dokuwiki`, + :doc:`../howto/drupal`, + :doc:`../howto/laravel`, + :doc:`../howto/lumen`, + :doc:`../howto/matomo`, + :doc:`../howto/mediawiki`, + :doc:`../howto/modx`, + :doc:`../howto/nextcloud`, + :doc:`../howto/phpbb`, + :doc:`../howto/phpmyadmin`, + :doc:`../howto/roundcube`, + :doc:`../howto/symfony`, + :doc:`../howto/wordpress`, and - :doc:`howto/yii` + :doc:`../howto/yii` howtos or a basic :ref:`sample `. @@ -4972,27 +4972,27 @@ are shared by all targets in the app. For Python-based examples, see our - :doc:`howto/bottle`, - :doc:`howto/datasette`, - :doc:`howto/django`, - :doc:`howto/djangochannels`, - :doc:`howto/falcon`, - :doc:`howto/fastapi`, - :doc:`howto/flask`, - :doc:`howto/guillotina`, - :doc:`howto/mailman`, - :doc:`howto/mercurial`, - :doc:`howto/moin`, - :doc:`howto/plone`, - :doc:`howto/pyramid`, - :doc:`howto/quart`, - :doc:`howto/responder`, - :doc:`howto/reviewboard`, - :doc:`howto/sanic`, - :doc:`howto/starlette`, - :doc:`howto/trac`, + :doc:`../howto/bottle`, + :doc:`../howto/datasette`, + :doc:`../howto/django`, + :doc:`../howto/djangochannels`, + :doc:`../howto/falcon`, + :doc:`../howto/fastapi`, + :doc:`../howto/flask`, + :doc:`../howto/guillotina`, + :doc:`../howto/mailman`, + :doc:`../howto/mercurial`, + :doc:`../howto/moin`, + :doc:`../howto/plone`, + :doc:`../howto/pyramid`, + :doc:`../howto/quart`, + :doc:`../howto/responder`, + :doc:`../howto/reviewboard`, + :doc:`../howto/sanic`, + :doc:`../howto/starlette`, + :doc:`../howto/trac`, and - :doc:`howto/zope` + :doc:`../howto/zope` howtos or a basic :ref:`sample `. @@ -5110,9 +5110,9 @@ to your app. For Ruby-based examples, see our - :doc:`howto/rails` + :doc:`../howto/rails` and - :doc:`howto/redmine` + :doc:`../howto/redmine` howtos or a basic :ref:`sample `. @@ -5366,9 +5366,9 @@ that stores instance-wide preferences. - String or an array of strings; lists enabled :program:`njs` - :doc:`modules `, + :doc:`modules <../scripting>`, uploaded - via the :doc:`control API `. + via the :doc:`control API <../controlapi>`. In turn, the **http** option exposes the following settings: @@ -5591,7 +5591,7 @@ is formed *after* the request has been handled. Besides :ref:`built-in variables `, you can use :program:`njs` -:doc:`templates ` +:doc:`templates <../scripting>` to define the log format: .. code-block:: json diff --git a/source/contents.rst b/source/contents.rst index 5cc97b95..840d2fd6 100644 --- a/source/contents.rst +++ b/source/contents.rst @@ -6,11 +6,10 @@ news installation controlapi - configuration + configuration/index scripting certificates statusapi - unitctl howto/index troubleshooting community diff --git a/source/controlapi.rst b/source/controlapi.rst index bff7e37b..04b1d54f 100644 --- a/source/controlapi.rst +++ b/source/controlapi.rst @@ -28,7 +28,7 @@ that comprises four primary options: * - **/config** - Used for general - :doc:`configuration management `. + :doc:`configuration management `. * - **/control** - Queried for diff --git a/source/howto/security.rst b/source/howto/security.rst index 1351ef76..b706ae85 100644 --- a/source/howto/security.rst +++ b/source/howto/security.rst @@ -366,7 +366,7 @@ notorious **777**, instead assigning them on a need-to-know basis. # find :nxt_ph:`/path/to/app/ ` -type f -exec :nxt_hint:`chmod ` u=rx,g=rx,o= {} \; # find :nxt_ph:`/path/to/static/app/files/ ` -type f -exec :nxt_hint:`chmod ` u=r,g=r,o= {} \; - #. To run a single app, :doc:`configure <../configuration>` Unit as follows: + #. To run a single app, :doc:`configure <../configuration/index>` Unit as follows: .. code-block:: json @@ -397,7 +397,7 @@ notorious **777**, instead assigning them on a need-to-know basis. } } - #. To run several apps side by side, :doc:`configure <../configuration>` + #. To run several apps side by side, :doc:`configure <../configuration/index>` them with appropriate user and group names. The following configuration distinguishes apps based on the request URI, but you can implement another scheme such as different listeners: diff --git a/source/news/2019/unit-1.8.0-released.rst b/source/news/2019/unit-1.8.0-released.rst index 8a51eb65..28a57fe9 100644 --- a/source/news/2019/unit-1.8.0-released.rst +++ b/source/news/2019/unit-1.8.0-released.rst @@ -42,7 +42,7 @@ applications, and leave us feedback. If you're a Jira user, please use this HowTo: https://unit.nginx.org/howto/jira/ More documentation is available in :doc:`../../installation` and -:doc:`../../configuration` sections. +:doc:`../../configuration/index` sections. We intend to use our open-development process to refine and improve the software and to eventually test and certify the software's compatibility diff --git a/source/scripting.rst b/source/scripting.rst index 2ed2a961..6d5b6b6a 100644 --- a/source/scripting.rst +++ b/source/scripting.rst @@ -8,7 +8,7 @@ JavaScript expressions, including function calls, in the form of `__ written in `NGINX JavaScript `__ ( :program:`njs` ). -They can be used with these :doc:`configuration ` options: +They can be used with these :doc:`configuration ` options: - **pass** in :ref:`listeners ` From c05c130c66755c0baed7bd1cd7aa673ec5e6473c Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Tue, 3 Sep 2024 19:38:50 +0100 Subject: [PATCH 28/45] Update source/news/2024/unit-1.33.0-released.rst --- source/news/2024/unit-1.33.0-released.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 70888eea..62d7e21c 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -42,7 +42,7 @@ Chunked request body support **************************** Unit can now accept chunked requests rather than returning **411 -Length Required**. This feature is experimental and can +Length Required**. This feature is experimental (not documented and subject to change), and can be enabled setting the **/settings/chunked_transform** configuration option to true. From d3f8259e06dd372adb440537669b6e2d8a7e9d5b Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Thu, 5 Sep 2024 14:12:29 +0100 Subject: [PATCH 29/45] docs: update features, config options, all of fame --- source/news/2024/index.rst | 2 +- source/news/2024/unit-1.33.0-released.rst | 17 ++++++++++++++++- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/source/news/2024/index.rst b/source/news/2024/index.rst index d8f26665..3171d7a5 100644 --- a/source/news/2024/index.rst +++ b/source/news/2024/index.rst @@ -6,7 +6,7 @@ News archive for the year 2024. .. nxt_news_entry:: :author: Unit Team - :description: Version 1.33.0 includes two new configuration options and a CLI tool. + :description: Version 1.33.0 includes three new configuration options and a CLI tool. :email: unit-owner@nginx.org :title: Unit 1.33.0 Released :url: news/2024/unit-1.33.0-released diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 62d7e21c..995ff12a 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -11,7 +11,7 @@ a number of new features and changes: New configuration options ************************* -This release introduces two new configuration options: +This release introduces three new configuration options: #. **listen_threads** @@ -30,6 +30,17 @@ This release introduces two new configuration options: This is analogous to the **backlog** parameter of the **listen** directive in NGINX. +#. **factory** + + This can be set under '/applications//factory' + + This option is a boolean value. If set to 'true', Unit treats 'callable' as + a factory. + + The default value is 'false'. + + NOTE: Unit does **not** support passing arguments to factories. + **************** unitctl CLI tool **************** @@ -139,6 +150,7 @@ making Unit better! With 1.33.0 we would like to send a shout out to: - Costas Drongos - Gourav - Remi Collet +- Robbie McKinstry Special thanks to Arjun for his fuzzing work. @@ -167,6 +179,9 @@ Full Changelog *) Feature: Unit ships with a new Rust based CLI application "unitctl". + *) Feature: the wasm-wasi-component language module now inherits the + processes environment. + *) Change: under systemd unit runs in forking mode (once again). *) Change: if building with njs, version 0.8.3 or later is now required. From 203dbc69fde8105583c2dfadb05834e707222b76 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Mon, 9 Sep 2024 10:38:59 +0100 Subject: [PATCH 30/45] Update source/news/2024/unit-1.33.0-released.rst --- source/news/2024/unit-1.33.0-released.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 995ff12a..b2f7026a 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -55,7 +55,7 @@ Chunked request body support Unit can now accept chunked requests rather than returning **411 Length Required**. This feature is experimental (not documented and subject to change), and can be enabled setting the **/settings/chunked_transform** configuration option -to true. +to **true**. ************************************* Changes in behavior and other updates From 1340b06c21b6685ca0e046aa97519745e03301d8 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Tue, 10 Sep 2024 13:31:18 +0100 Subject: [PATCH 31/45] docs: add bugfix --- source/news/2024/unit-1.33.0-released.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index b2f7026a..1010a451 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -200,6 +200,8 @@ Full Changelog *) Change: default listen(2) backlog on Linux now defaults to Kernel default. + *) Bugfix: fix a crash when interrupting a download via a proxy. + *) Bugfix: don't create the $runstatedir directory which triggered an Alpine packaging error. From dba084a80b25a87a824ba4a56cb7e8295a6552be Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 11 Sep 2024 12:22:07 +0100 Subject: [PATCH 32/45] docs: remove sudo on copy --- source/contents.rst | 1 + source/theme/static/script.js | 3 +-- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/contents.rst b/source/contents.rst index 840d2fd6..2b4c0f35 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/theme/static/script.js b/source/theme/static/script.js index eadd2eec..b578d0da 100644 --- a/source/theme/static/script.js +++ b/source/theme/static/script.js @@ -149,8 +149,7 @@ function nxt_copy_console(text) { line = trimmed.replace(/^\$\s*/, '') break case '#': - line = trimmed.replace(/^#\s*/, 'sudo ') - .replace(/\|\s*/g, '| sudo ') + line = trimmed.replace(/^#\s*/, '') break default: continue From d91b4fe39c361401ba1eca7d0a95c78bc37a5fb9 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Thu, 12 Sep 2024 15:55:05 +0100 Subject: [PATCH 33/45] docs: add changes from PR 167 --- source/configuration/index.rst | 54 ++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/source/configuration/index.rst b/source/configuration/index.rst index 17fa53bb..cdfdcdea 100644 --- a/source/configuration/index.rst +++ b/source/configuration/index.rst @@ -99,6 +99,25 @@ Available listener options: defines SSL/TLS :ref:`settings `. + * - **backlog** + - Integer; + controls the 'backlog' parameter to the *listen(2)* system-call. + This essentially limits the number of pending connections waiting + to be accepted. + + The default varies by system. + + On Linux, FreeBSD, OpenBSD and macOS the default is **-1** which + means use the OS default. For example. on Linux since 5.4, this is + **4096** (previously **128**) and on FreeBSD it's **128**. + + On other systems the default is **511**. + + NOTE: Whatever limit you set here will be limited by the OS + system-wide sysctl. For example. on Linux that is + **net.core.somaxconn** and on BSD it's **kern.ipc.somaxconn** + + *(since 1.33.0)* Here, a local listener accepts requests at port 8300 and passes them to the **blogs** app @@ -3293,14 +3312,15 @@ shared between all application languages: * - **stderr**, **stdout** - Strings; - filenames where Unit redirects - the application's output. + filenames where Unit redirects the application's output. - The default is **/dev/null**. + The default when running *with* **--no-daemon** is to send + *stdout* to the *console* and *stderr* to Unit's *log*. - When running in **--no-daemon** mode, application output - is always redirected to - :ref:`Unit's log file `. + The default when running *without* **--no-daemon** is to send + *stdout* to */dev/null* and *stderr* to Unit's *log*. + + These options have *no* effect when running with **--no-daemon**. * - **user** - String; @@ -4720,6 +4740,16 @@ you have: The default is **application**. + * - **factory** + - Boolean: + when enabled, Unit treats **callable** as a factory. + + The default is **false**. + + **Note:** Unit does *not* support passing arguments to factories. + + *(since 1.33.0)* + * - **home** - String; path to the app's @@ -5357,6 +5387,16 @@ that stores instance-wide preferences. * - Option - Description + * - **listen_threads** + - Integer; + controls the number of router threads created to handle client + connections. Each thread includes all the configured listeners. + + By default, we create as many threads as the number of CPUs that + are available to run on. + + *(since 1.33.0)* + * - **http** - Object; fine-tunes handling of HTTP requests @@ -5469,6 +5509,8 @@ In turn, the **http** option exposes the following settings: The default is **true**. + *(since 1.30.0)* + * - **static** - Object; configures static asset handling. From 147e7f0a6ffdaa3df7174864bf3fa19e0c7a1ff2 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Thu, 12 Sep 2024 17:32:47 +0100 Subject: [PATCH 34/45] docs: split code blocks --- source/certificates.rst | 3 + source/configuration/index.rst | 24 ++ source/controlapi.rst | 9 + source/howto/apollo.rst | 12 + source/howto/cakephp.rst | 3 + source/howto/catalyst.rst | 9 + source/howto/certbot.rst | 11 + source/howto/djangochannels.rst | 9 + source/howto/docker.rst | 25 ++ source/howto/dokuwiki.rst | 9 + source/howto/express.rst | 12 + source/howto/grafana.rst | 9 + source/howto/guillotina.rst | 2 + source/howto/jira.rst | 39 ++ source/howto/koa.rst | 9 + source/howto/laravel.rst | 3 + source/howto/lumen.rst | 3 + source/howto/mediawiki.rst | 6 + source/howto/mercurial.rst | 18 + source/howto/modules.rst | 29 ++ source/howto/moin.rst | 42 ++ source/howto/opengrok.rst | 3 + source/howto/plone.rst | 12 + source/howto/quart.rst | 3 + source/howto/rails.rst | 3 + source/howto/responder.rst | 3 + source/howto/reviewboard.rst | 3 + source/howto/roundcube.rst | 3 + source/howto/samples.rst | 52 +++ source/howto/security.rst | 45 +++ source/howto/source.rst | 174 ++++++++- source/howto/springboot.rst | 6 + source/howto/starlette.rst | 4 + source/howto/symfony.rst | 3 + source/howto/trac.rst | 33 ++ source/howto/yii.rst | 6 + source/howto/zope.rst | 27 ++ source/installation.rst | 442 ++++++++++++++++++++++ source/news/2022/unit-1.29.0-released.rst | 12 + source/troubleshooting.rst | 17 + source/unitctl.rst | 9 + 41 files changed, 1145 insertions(+), 1 deletion(-) diff --git a/source/certificates.rst b/source/certificates.rst index cd3d3b4e..4a5f1db4 100644 --- a/source/certificates.rst +++ b/source/certificates.rst @@ -133,6 +133,9 @@ as **GET**-table JSON using **/certificates**: # curl -X GET --unix-socket :nxt_ph:`/path/to/control.unit.sock ` \ http://localhost/certificates/:nxt_hint:`bundle `/chain/0/ + + .. code-block:: console + # curl -X GET --unix-socket :nxt_ph:`/path/to/control.unit.sock ` \ http://localhost/certificates/:nxt_hint:`bundle `/chain/0/subject/alt_names/0/ diff --git a/source/configuration/index.rst b/source/configuration/index.rst index cdfdcdea..a8c6ff95 100644 --- a/source/configuration/index.rst +++ b/source/configuration/index.rst @@ -421,6 +421,8 @@ The **tickets** option works as follows: LoYjFVxpUFFOj4TzGkr5MsSIRMjhuh8RCsVvtIJiQ12FGhn0nhvvQsEND1+OugQ7 + .. code-block:: console + $ openssl rand -base64 80 GQczhdXawyhTrWrtOXI7l3YYUY98PrFYzjGhBbiQsAWgaxm+mbkm4MmZZpDw0tkK @@ -1971,14 +1973,20 @@ from the incoming requests: HTTP/1.1 201 Created +.. code-block:: console + $ curl -i -X PUT http://localhost HTTP/1.1 202 Accepted +.. code-block:: console + $ curl -i -X POST http://localhost HTTP/1.1 203 Non-Authoritative Information +.. code-block:: console + $ curl -i --head http://localhost # Bumpy ride ahead, no route defined HTTP/1.1 404 Not Found @@ -2047,6 +2055,9 @@ it is considered empty. .. code-block:: console $ curl http://localhost/blog # Targets the 'blog' app + + .. code-block:: console + $ curl http://localhost/sandbox # Targets the 'sandbox' app A different approach puts the **Host** header field @@ -2777,11 +2788,16 @@ won't be resolved. .. code-block:: console $ mkdir -p /www/localhost/static/ && cd /www/localhost/static/ + + .. code-block:: console + $ cat > index.html << EOF > index.html > EOF + .. code-block:: console + $ ln -s index.html /www/localhost/static/symlink If symlink resolution is enabled @@ -2794,6 +2810,8 @@ won't be resolved. index.html + .. code-block:: console + $ curl http://localhost/symlink index.html @@ -2819,6 +2837,8 @@ won't be resolved. index.html + .. code-block:: console + $ curl http://localhost/symlink Error 403

Error 403. @@ -3666,6 +3686,8 @@ and set the **memory.high** limit: cpuset cpu io memory pids +.. code-block:: console + # echo 1G > /sys/fs/cgroup:nxt_hint:`/staging/app `/memory.high For more details @@ -3986,6 +4008,8 @@ and rebuild the app. 0 + .. code-block:: console + $ go env -w CGO_ENABLED=1 - If you installed Unit from the diff --git a/source/controlapi.rst b/source/controlapi.rst index 04b1d54f..c0461147 100644 --- a/source/controlapi.rst +++ b/source/controlapi.rst @@ -181,6 +181,9 @@ OpenAPI specification .. code-block:: console $ docker build --tag=unit-openapi -f unit-openapi.Dockerfile . + + .. code-block:: console + $ docker run -d -p 8765:8765 -p 8080:8080 unit-openapi Next, open **http://localhost:8765** in a browser. @@ -366,6 +369,8 @@ provided you supply the right JSON: # curl -X PUT -d '{ "pass": "applications/blogs" }' --unix-socket \ :nxt_ph:`/path/to/control.unit.sock ` http://localhost/config/listeners/127.0.0.1:8300 +.. code-block:: console + # curl -X PUT -d '"applications/blogs"' --unix-socket :nxt_ph:`/path/to/control.unit.sock ` \ http://localhost/config/listeners/127.0.0.1:8300/pass @@ -460,9 +465,13 @@ adding a URI-based route to the development version of the app: ] EOF +.. code-block:: console + # curl -X PUT --data-binary @config.json --unix-socket \ :nxt_ph:`/path/to/control.unit.sock ` http://localhost/config/routes +.. code-block:: console + # curl -X PUT -d '"routes"' --unix-socket \ :nxt_ph:`/path/to/control.unit.sock ` 'http://localhost/config/listeners/*:8400/pass' diff --git a/source/howto/apollo.rst b/source/howto/apollo.rst index 8fbecb3f..e44db602 100644 --- a/source/howto/apollo.rst +++ b/source/howto/apollo.rst @@ -23,8 +23,17 @@ using Unit: .. code-block:: console $ mkdir -p :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ npm install @apollo/server graphql + + .. code-block:: console + # npm link unit-http #. Create the `middleware @@ -35,6 +44,9 @@ using Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ npm init Next, add the following code: diff --git a/source/howto/cakephp.rst b/source/howto/cakephp.rst index 337daee9..3ca551c6 100644 --- a/source/howto/cakephp.rst +++ b/source/howto/cakephp.rst @@ -17,6 +17,9 @@ To run apps based on the `CakePHP `_ framework using Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/ ` + + .. code-block:: console + $ composer create-project --prefer-dist cakephp/app:4.* :nxt_ph:`app ` This creates the app's directory tree at **/path/to/app/**. Its diff --git a/source/howto/catalyst.rst b/source/howto/catalyst.rst index 80dae1d1..fd8f359e 100644 --- a/source/howto/catalyst.rst +++ b/source/howto/catalyst.rst @@ -21,8 +21,17 @@ To run apps based on the `Catalyst .. code-block:: console $ cd :nxt_ph:`/path/to/ ` + + .. code-block:: console + $ catalyst.pl :nxt_ph:`app ` + + .. code-block:: console + $ cd app + + .. code-block:: console + $ perl Makefile.PL Make sure the app's **.psgi** file includes the **lib/** diff --git a/source/howto/certbot.rst b/source/howto/certbot.rst index 586f6803..a5d491a7 100644 --- a/source/howto/certbot.rst +++ b/source/howto/certbot.rst @@ -101,6 +101,8 @@ Generating Certificates # cat /etc/letsencrypt/live/www.example.com/fullchain.pem \ /etc/letsencrypt/live/www.example.com/privkey.pem > :nxt_ph:`bundle1.pem ` + .. code-block:: console + # curl -X PUT --data-binary @:nxt_ph:`bundle1.pem ` \ --unix-socket :nxt_ph:`/path/to/control.unit.sock ` \ http://localhost/certificates/:nxt_ph:`certbot1 ` @@ -170,9 +172,13 @@ For manual renewal and rollover: 1: Keep the existing certificate for now 2: Renew & replace the cert (may be subject to CA rate limits) + .. code-block:: console + # cat /etc/letsencrypt/live/www.example.com/fullchain.pem \ /etc/letsencrypt/live/www.example.com/privkey.pem > :nxt_ph:`bundle2.pem ` + .. code-block:: console + # curl -X PUT --data-binary @:nxt_ph:`bundle2.pem ` \ --unix-socket :nxt_ph:`/path/to/control.unit.sock ` \ http://localhost/certificates/:nxt_ph:`certbot2 ` @@ -229,9 +235,12 @@ For manual renewal and rollover: # cat /etc/letsencrypt/live/cdn.example.com/fullchain.pem \ /etc/letsencrypt/live/cdn.example.com/privkey.pem > :nxt_hint:`cdn.example.com.pem ` + .. code-block:: console + # cat /etc/letsencrypt/live/www.example.com/fullchain.pem \ /etc/letsencrypt/live/www.example.com/privkey.pem > :nxt_hint:`www.example.com.pem ` + .. code-block:: console # curl -X PUT --data-binary @:nxt_hint:`cdn.example.com.pem ` \ --unix-socket :nxt_ph:`/path/to/control.unit.sock ` \ @@ -241,6 +250,8 @@ For manual renewal and rollover: "success": "Certificate chain uploaded." } + .. code-block:: console + # curl -X PUT --data-binary @:nxt_hint:`www.example.com.pem ` \ --unix-socket :nxt_ph:`/path/to/control.unit.sock ` \ http://localhost/certificates/:nxt_hint:`www.example.com ` diff --git a/source/howto/djangochannels.rst b/source/howto/djangochannels.rst index ff57b89d..d48e87f0 100644 --- a/source/howto/djangochannels.rst +++ b/source/howto/djangochannels.rst @@ -21,8 +21,17 @@ To run Django apps using the |app| `framework .. code-block:: console $ cd :nxt_ph:`/path/to/venv/ ` + + .. code-block:: console + $ source bin/activate + + .. code-block:: console + $ pip install channels + + .. code-block:: console + $ deactivate #. Create a Django project. Here, we'll use the `tutorial chat app diff --git a/source/howto/docker.rst b/source/howto/docker.rst index 4cceab10..ec694ddc 100644 --- a/source/howto/docker.rst +++ b/source/howto/docker.rst @@ -64,7 +64,13 @@ official **hello, world** app: .. code-block:: console $ cd :nxt_ph:`/path/to/app/ ` + +.. code-block:: console + $ mkdir webapp + +.. code-block:: console + $ cat << EOF > webapp/wsgi.py from flask import Flask @@ -91,6 +97,9 @@ app: .. code-block:: console $ mkdir config + +.. code-block:: console + $ cat << EOF > config/config.json { @@ -117,7 +126,13 @@ Finally, let's create **log/** and **state/** directories to store Unit .. code-block:: console $ mkdir log + +.. code-block:: console + $ touch log/unit.log + +.. code-block:: console + $ mkdir state Our file structure so far: @@ -315,12 +330,16 @@ Unit's state: $ docker build --tag=:nxt_hint:`unit-expressapp ` . +.. code-block:: console + $ export UNIT=$( \ docker run -d \ --mount type=bind,src="$(pwd)/myapp/config.json",dst=/docker-entrypoint.d/config.json \ -p 8080:8080 unit-expressapp \ ) +.. code-block:: console + $ curl -X GET localhost:8080 Hello, Unit! @@ -358,16 +377,22 @@ the :ref:`control API `: ... EOF +.. code-block:: console + $ export UNIT=$( \ docker run -d \ --mount type=bind,src="$(pwd)/myapp/new-config.json",dst=/cfg/new-config.json \ unit-expressapp \ ) +.. code-block:: console + $ docker exec -ti $UNIT curl -X PUT --data-binary @/cfg/new-config.json \ --unix-socket /var/run/control.unit.sock \ http://localhost/config +.. code-block:: console + $ docker exec -ti $UNIT curl -X PUT -d '"/www/newapp/"' \ --unix-socket /var/run/control.unit.sock \ http://localhost/config/applications/express/working_directory diff --git a/source/howto/dokuwiki.rst b/source/howto/dokuwiki.rst index 95b30bd5..3273497c 100644 --- a/source/howto/dokuwiki.rst +++ b/source/howto/dokuwiki.rst @@ -21,8 +21,17 @@ using Unit: .. code-block:: console $ mkdir -p :nxt_ph:`/path/to/app/ ` && cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ wget https://download.dokuwiki.org/src/dokuwiki/dokuwiki-stable.tgz + + .. code-block:: console + $ tar xvzf dokuwiki-stable.tgz :nxt_hint:`--strip-components `=1 + + .. code-block:: console + $ rm dokuwiki-stable.tgz #. .. include:: ../include/howto_change_ownership.rst diff --git a/source/howto/express.rst b/source/howto/express.rst index f1e9213f..8095f738 100644 --- a/source/howto/express.rst +++ b/source/howto/express.rst @@ -23,8 +23,17 @@ using Unit: .. code-block:: console $ mkdir -p :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ npm install express --save + + .. code-block:: console + # npm link unit-http #. Create your Express `app @@ -34,6 +43,9 @@ using Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ npm init Next, add your application code: diff --git a/source/howto/grafana.rst b/source/howto/grafana.rst index 6c34c0ab..c430d384 100644 --- a/source/howto/grafana.rst +++ b/source/howto/grafana.rst @@ -25,7 +25,13 @@ so we can :ref:`configure it ` to run on Unit. .. code-block:: console $ cd :nxt_hint:`$GOPATH/src/github.com/grafana/grafana ` + + .. code-block:: console + $ curl -O https://unit.nginx.org/_downloads/grafana.patch + + .. code-block:: console + $ patch -p1 < grafana.patch Or update the sources manually. In **conf/defaults.ini**: @@ -133,6 +139,9 @@ so we can :ref:`configure it ` to run on Unit. .. code-block:: console # chown -R :nxt_hint:`unit:unit ` :nxt_hint:`$GOPATH/src/github.com/grafana/grafana ` + + .. code-block:: console + # chown :nxt_hint:`unit:unit ` :nxt_hint:`$GOPATH/bin/grafana-server ` .. note:: diff --git a/source/howto/guillotina.rst b/source/howto/guillotina.rst index a0f4034b..10c97761 100644 --- a/source/howto/guillotina.rst +++ b/source/howto/guillotina.rst @@ -100,6 +100,8 @@ To run apps built with the `Guillotina {"@type":"Container","id":"container","title":"container"} + .. code-block:: console + $ curl --user root:root http://localhost/db/container { diff --git a/source/howto/jira.rst b/source/howto/jira.rst index e5583e95..d62db912 100644 --- a/source/howto/jira.rst +++ b/source/howto/jira.rst @@ -24,7 +24,13 @@ To run `Atlassian Jira `_ using Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ curl https://www.atlassian.com/software/jira/downloads/binary/atlassian-jira-software-8.19.1.tar.gz -O -C - + + .. code-block:: console + $ tar xzf atlassian-jira-core-8.19.1.tar.gz --strip-components 1 #. Download |app|'s third-party dependencies to the **lib** subdirectory: @@ -32,15 +38,45 @@ To run `Atlassian Jira `_ using Unit: .. code-block:: console $ cd lib/ + + .. code-block:: console + $ curl https://github.com/mar0x/unit-transaction-init/releases/download/2.0/transaction-init-2.0.jar -O -C - + + .. code-block:: console + $ curl https://repo1.maven.org/maven2/com/atomikos/atomikos-util/5.0.8/atomikos-util-5.0.8.jar -O -C - + + .. code-block:: console + $ curl https://repo1.maven.org/maven2/com/atomikos/transactions-api/5.0.8/transactions-api-5.0.8.jar -O -C - + + .. code-block:: console + $ curl https://repo1.maven.org/maven2/com/atomikos/transactions-jdbc/5.0.8/transactions-jdbc-5.0.8.jar -O -C - + + .. code-block:: console + $ curl https://repo1.maven.org/maven2/com/atomikos/transactions-jta/5.0.8/transactions-jta-5.0.8.jar -O -C - + + .. code-block:: console + $ curl https://repo1.maven.org/maven2/com/atomikos/transactions/5.0.8/transactions-5.0.8.jar -O -C - + + .. code-block:: console + $ curl https://repo1.maven.org/maven2/javax/transaction/jta/1.1/jta-1.1.jar -O -C - + + .. code-block:: console + $ curl https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-jndi/11.0.6/jetty-jndi-10.0.6.jar -O -C - + + .. code-block:: console + $ curl https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-plus/11.0.6/jetty-plus-10.0.6.jar -O -C - + + .. code-block:: console + $ curl https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-util/11.0.6/jetty-util-10.0.6.jar -O -C - Later, these **.jar** files will be listed in the **classpath** @@ -53,6 +89,9 @@ To run `Atlassian Jira `_ using Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ sed -i 's#comp/env/UserTransaction#comp/UserTransaction#g' \ atlassian-jira/WEB-INF/classes/entityengine.xml diff --git a/source/howto/koa.rst b/source/howto/koa.rst index 7636bf43..fbb9a953 100644 --- a/source/howto/koa.rst +++ b/source/howto/koa.rst @@ -21,8 +21,17 @@ To run apps built with the `Koa `_ web framework using Unit: .. code-block:: console $ mkdir -p :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ npm install koa + + .. code-block:: console + # npm link unit-http #. Let’s try a version of the `tutorial app diff --git a/source/howto/laravel.rst b/source/howto/laravel.rst index 0ea16c34..9bd79656 100644 --- a/source/howto/laravel.rst +++ b/source/howto/laravel.rst @@ -20,6 +20,9 @@ To run apps based on the `Laravel `_ framework using Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/ ` + + .. code-block:: console + $ composer create-project laravel/laravel :nxt_ph:`app ` #. .. include:: ../include/howto_change_ownership.rst diff --git a/source/howto/lumen.rst b/source/howto/lumen.rst index 789e3849..18fa4039 100644 --- a/source/howto/lumen.rst +++ b/source/howto/lumen.rst @@ -21,6 +21,9 @@ Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/ ` + + .. code-block:: console + $ composer create-project laravel/lumen :nxt_ph:`app ` #. .. include:: ../include/howto_change_ownership.rst diff --git a/source/howto/mediawiki.rst b/source/howto/mediawiki.rst index e518c5dc..65666d90 100644 --- a/source/howto/mediawiki.rst +++ b/source/howto/mediawiki.rst @@ -137,7 +137,13 @@ documentation platform using Unit: .. code-block:: console $ chmod 600 LocalSettings.php + + .. code-block:: console + # chown :nxt_ph:`unit:unit ` LocalSettings.php + + .. code-block:: console + # mv LocalSettings.php :nxt_ph:`/path/to/app/ ` #. After installation, add a match condition to the first step to disable diff --git a/source/howto/mercurial.rst b/source/howto/mercurial.rst index 2c88d68e..f4c6e60d 100644 --- a/source/howto/mercurial.rst +++ b/source/howto/mercurial.rst @@ -67,11 +67,29 @@ control system using Unit: .. code-block:: console $ hg config --edit + + .. code-block:: console + $ hg clone http://localhost/ project/ + + .. code-block:: console + $ cd project/ + + .. code-block:: console + $ touch hg_rocks.txt + + .. code-block:: console + $ hg add + + .. code-block:: console + $ hg commit -m 'Official: Mercurial on Unit rocks!' + + .. code-block:: console + $ hg push .. image:: ../images/hg.png diff --git a/source/howto/modules.rst b/source/howto/modules.rst index 093ecec3..44d3e08b 100644 --- a/source/howto/modules.rst +++ b/source/howto/modules.rst @@ -138,13 +138,31 @@ adjust the command samples as needed to fit your scenario. .. code-block:: console # apt update + + .. code-block:: console + # apt install :nxt_hint:`ca-certificates apt-transport-https debian-archive-keyring ` + + .. code-block:: console + # curl --output /usr/share/keyrings/php-keyring.gpg \ :nxt_hint:`https://packages.sury.org/php/apt.gpg ` + + .. code-block:: console + # echo "deb [signed-by=/usr/share/keyrings/php-keyring.gpg] \ https://packages.sury.org/php/ buster main" > /etc/apt/sources.list.d/php.list + + .. code-block:: console + # apt update + + .. code-block:: console + # apt install php7.3 + + .. code-block:: console + # apt install :nxt_hint:`php-dev libphp-embed ` #. Create a staging directory for your package: @@ -223,6 +241,9 @@ adjust the command samples as needed to fit your scenario. .. code-block:: console # yum install -y php-7.3.8 + + .. code-block:: console + # yum install php-devel php-embedded #. Install RPM development tools and prepare the directory structure: @@ -230,6 +251,9 @@ adjust the command samples as needed to fit your scenario. .. code-block:: console # yum install -y rpmdevtools + + .. code-block:: console + $ rpmdev-setuptree #. Create a **.spec** `file @@ -239,6 +263,9 @@ adjust the command samples as needed to fit your scenario. .. code-block:: console $ cd ~/rpmbuild/SPECS + + .. code-block:: console + $ rpmdev-newspec unit-php7.3 #. Run :program:`unitd --version` and note the :program:`./configure` @@ -318,4 +345,6 @@ adjust the command samples as needed to fit your scenario. Wrote: /home/user/rpmbuild/RPMS//unit-php7.3-..rpm ... + .. code-block:: console + # yum install -y /home/user/rpmbuild/RPMS//unit-php7.3-..rpm diff --git a/source/howto/moin.rst b/source/howto/moin.rst index 94b203a4..dd01f142 100644 --- a/source/howto/moin.rst +++ b/source/howto/moin.rst @@ -48,10 +48,25 @@ To run the `MoinMoin `_ wiki engine using Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ mkdir single/ + + .. code-block:: console + $ cp :nxt_hint:`wiki/config/wikiconfig.py ` single/ + + .. code-block:: console + $ cp -r wiki/data/ single/data/ + + .. code-block:: console + $ cp -r wiki/underlay/ single/underlay/ + + .. code-block:: console + $ cp :nxt_hint:`wiki/server/moin.wsgi ` single/moin.py Next, `edit @@ -67,14 +82,41 @@ To run the `MoinMoin `_ wiki engine using Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ mkdir multi/ multi/wiki1/ multi/wiki2/ + + .. code-block:: console + $ cp wiki/config/wikifarm/* multi/ + + .. code-block:: console + $ cp :nxt_hint:`wiki/config/wikiconfig.py ` multi/wiki1.py + + .. code-block:: console + $ cp :nxt_hint:`wiki/config/wikiconfig.py ` multi/wiki2.py + + .. code-block:: console + $ cp -r wiki/data/ multi/wiki1/data/ + + .. code-block:: console + $ cp -r wiki/data/ multi/wiki2/data/ + + .. code-block:: console + $ cp -r wiki/underlay/ multi/wiki1/underlay/ + + .. code-block:: console + $ cp -r wiki/underlay/ multi/wiki2/underlay/ + + .. code-block:: console + $ cp :nxt_hint:`wiki/server/moin.wsgi ` multi/moin.py Next, `edit diff --git a/source/howto/opengrok.rst b/source/howto/opengrok.rst index 863f226a..9fdbb02c 100644 --- a/source/howto/opengrok.rst +++ b/source/howto/opengrok.rst @@ -17,6 +17,9 @@ To run the `OpenGrok .. code-block:: console $ mkdir -p :nxt_ph:`/path/to/app/ `{src,data,dist,etc,log} + + .. code-block:: console + $ tar -C :nxt_ph:`/path/to/app/ `dist --strip-components=1 -xzf opengrok-:nxt_ph:`X.Y.Z `.tar.gz Our servlet container is Unit so we can repackage the **source.war** diff --git a/source/howto/plone.rst b/source/howto/plone.rst index ce4e98fd..9adbdaee 100644 --- a/source/howto/plone.rst +++ b/source/howto/plone.rst @@ -23,9 +23,18 @@ To run the `Plone `_ content management system using Unit: .. code-block:: console $ mkdir /tmp/plone && cd /tmp/plone/ + + .. code-block:: console + $ wget https://launchpad.net/plone/:nxt_ph:`A.B `/:nxt_ph:`A.B.C `/+download/Plone-:nxt_ph:`A.B.C `-UnifiedInstaller-1.0.tgz + + .. code-block:: console + $ tar xzvf Plone-:nxt_ph:`A.B.C `-UnifiedInstaller-1.0.tgz \ :nxt_hint:`--strip-components `=1 + + .. code-block:: console + $ ./install.sh --target=:nxt_ph:`/path/to/app/ ` \ --with-python=:nxt_ph:`/full/path/to/python ` \ standalone @@ -73,6 +82,9 @@ To run the `Plone `_ content management system using Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/app/ `zinstance/ + + .. code-block:: console + $ bin/buildout -c wsgi.cfg ... diff --git a/source/howto/quart.rst b/source/howto/quart.rst index 64ce8165..c596b70f 100644 --- a/source/howto/quart.rst +++ b/source/howto/quart.rst @@ -71,6 +71,9 @@ To run apps built with the `Quart

Hello, World!

+ + .. code-block:: console + $ wscat -c ws://localhost/ws < Hello, World! diff --git a/source/howto/rails.rst b/source/howto/rails.rst index 43abaeba..41644cfd 100644 --- a/source/howto/rails.rst +++ b/source/howto/rails.rst @@ -18,6 +18,9 @@ using Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/ ` + + .. code-block:: console + $ rails new :nxt_ph:`app ` This creates the app's directory tree at **/path/to/app/**; its diff --git a/source/howto/responder.rst b/source/howto/responder.rst index 803d497f..85274bce 100644 --- a/source/howto/responder.rst +++ b/source/howto/responder.rst @@ -74,6 +74,9 @@ To run apps built with the `Responder Hello, World! + + .. code-block:: console + $ curl http://localhost/hello/JohnDoe Hello, JohnDoe! diff --git a/source/howto/reviewboard.rst b/source/howto/reviewboard.rst index 78d7e915..eb612adf 100644 --- a/source/howto/reviewboard.rst +++ b/source/howto/reviewboard.rst @@ -54,6 +54,9 @@ To run the `Review Board .. code-block:: console $ chmod u+w :nxt_ph:`/path/to/app/ `htdocs/media/uploaded/ + + .. code-block:: console + $ chmod u+w :nxt_ph:`/path/to/app/ `data/ #. Next, :ref:`prepare ` the |app| configuration for Unit diff --git a/source/howto/roundcube.rst b/source/howto/roundcube.rst index 387b0f5b..693b748e 100644 --- a/source/howto/roundcube.rst +++ b/source/howto/roundcube.rst @@ -77,6 +77,9 @@ To run the `Roundcube `_ webmail platform using Unit: # curl -X PUT -d ':nxt_ph:`"/path/to/app/ `public_html$uri"' --unix-socket \ :nxt_ph:`/path/to/control.unit.sock ` :nxt_hint:`http://localhost/config/routes/1/action/share ` + + .. code-block:: console + # curl -X PUT -d '":nxt_ph:`/path/to/app/ `public_html/"' --unix-socket \ :nxt_ph:`/path/to/control.unit.sock ` :nxt_hint:`http://localhost/config/applications/roundcube/root ` diff --git a/source/howto/samples.rst b/source/howto/samples.rst index e6b3a7d7..e496fb7f 100644 --- a/source/howto/samples.rst +++ b/source/howto/samples.rst @@ -60,6 +60,8 @@ Upload the :ref:`app config ` to Unit and test it: } }' --unix-socket :nxt_ph:`/path/to/control.unit.sock ` http://localhost/config/ +.. code-block:: console + $ curl http://localhost:8080 Hello, Go on Unit! @@ -148,6 +150,8 @@ Upload the :ref:`app config ` to Unit and test it: } }' --unix-socket :nxt_ph:`/path/to/control.unit.sock ` http://localhost/config/ +.. code-block:: console + $ curl http://localhost:8080 Hello, JSP on Unit! @@ -224,7 +228,13 @@ Make it executable and link the Node.js language package you've :ref:`installed .. code-block:: console $ cd /www + +.. code-block:: console + $ chmod +x app.js + +.. code-block:: console + $ npm link unit-http Upload the :ref:`app config ` to Unit and test it: @@ -246,6 +256,8 @@ Upload the :ref:`app config ` to Unit and test it: } }' --unix-socket :nxt_ph:`/path/to/control.unit.sock ` http://localhost/config/ +.. code-block:: console + $ curl http://localhost:8080 Hello, Node.js on Unit! @@ -320,6 +332,8 @@ Upload the :ref:`app config ` to Unit and test it: } }' --unix-socket :nxt_ph:`/path/to/control.unit.sock ` http://localhost/config/ +.. code-block:: console + $ curl http://localhost:8080 Hello, Perl on Unit! @@ -450,6 +464,8 @@ Upload the :ref:`app config ` to Unit and test it: } }' --unix-socket :nxt_ph:`/path/to/control.unit.sock ` http://localhost/config/ +.. code-block:: console + $ curl http://localhost:8080 Hello, Python on Unit! @@ -517,6 +533,8 @@ Upload the :ref:`app config ` to Unit and test it: } }' --unix-socket :nxt_ph:`/path/to/control.unit.sock ` http://localhost/config/ +.. code-block:: console + $ curl http://localhost:8080 Hello, Ruby on Unit! @@ -588,7 +606,13 @@ WebAssembly (Wasm) .. code-block:: console $ git clone https://github.com/sunfishcode/hello-wasi-http + + .. code-block:: console + $ cd hello-wasi-http + + .. code-block:: console + $ cargo component build The output of the build command should be similar to this: @@ -675,7 +699,13 @@ WebAssembly (Wasm) .. code-block:: console $ cargo init --lib wasm_on_unit + + .. code-block:: console + $ cd wasm_on_unit/ + + .. code-block:: console + $ cargo add unit-wasm Append the following to **Cargo.toml**: @@ -725,6 +755,8 @@ WebAssembly (Wasm) } }' --unix-socket :nxt_ph:`/path/to/control.unit.sock ` http://localhost/config/ + .. code-block:: console + $ curl http://localhost:8080 * Welcome to WebAssembly in Rust on Unit! [libunit-wasm (0.3.0/0x00030000)] * @@ -753,9 +785,21 @@ WebAssembly (Wasm) .. code-block:: console $ git clone https://github.com/nginx/unit-wasm/ + + .. code-block:: console + $ cd unit-wasm + + .. code-block:: console + $ make help # Explore your options first + + .. code-block:: console + $ make WASI_SYSROOT=:nxt_ph:`/path/to/wasi-sysroot/ ` examples # C examples + + .. code-block:: console + $ make WASI_SYSROOT=:nxt_ph:`/path/to/wasi-sysroot/ ` examples-rust # Rust examples .. note:: @@ -773,9 +817,17 @@ WebAssembly (Wasm) $ wget -O- https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-20/libclang_rt.builtins-wasm32-wasi-20.0.tar.gz \ | tar zxf - # Unpacks to lib/wasi/ in the current directory + + .. code-block:: console + $ clang -print-runtime-dir # Double-check the run-time directory, which is OS-dependent :nxt_ph:`/path/to/runtime/dir `/linux + .. code-block:: console + # mkdir :nxt_ph:`/path/to/runtime/dir `/wasi # Note the last part of the pathname + + .. code-block:: console + # cp :nxt_hint:`lib/wasi/ `libclang_rt.builtins-wasm32.a :nxt_ph:`/path/to/runtime/dir `/wasi/ diff --git a/source/howto/security.rst b/source/howto/security.rst index b706ae85..5dfa3c36 100644 --- a/source/howto/security.rst +++ b/source/howto/security.rst @@ -85,6 +85,9 @@ safe. .. code-block:: console $ ssh -N -L :nxt_hint:`./here.sock `::nxt_ph:`/path/to/control.unit.sock ` root@:nxt_hint:`unit.example.com ` & + + .. code-block:: console + $ curl --unix-socket :nxt_hint:`./here.sock ` { @@ -103,6 +106,9 @@ safe. .. code-block:: console # unitd --control 203.0.113.14:8080 + + .. code-block:: console + $ curl 203.0.113.14:8080 { @@ -119,6 +125,9 @@ safe. .. code-block:: console # unitd --control 127.0.0.1:8080 + + .. code-block:: console + $ curl 203.0.113.14:8080 curl: (7) Failed to connect to 203.0.113.14 port 8080: Connection refused @@ -146,10 +155,14 @@ safe. --state DIRECTORY set state directory name default: ":nxt_ph:`/default/path/to/unit/state/ `" + .. subs-code-block:: console + $ ps ax | grep unitd ... unit: main v|version| [... --state :nxt_ph:`/path/to/unit/state/ ` ...] + .. subs-code-block:: console + # ls -l :nxt_ph:`/path/to/unit/state/ ` drwx------ 2 root root 4096 ... @@ -230,6 +243,8 @@ notorious **777**, instead assigning them on a need-to-know basis. --group GROUP set non-privileged processes to run as specified group default: user's primary group + .. subs-code-block:: console + $ ps ax | grep unitd ... unit: main v|version| [... --user :nxt_ph:`unit_user ` --group :nxt_ph:`unit_group ` ...] @@ -272,8 +287,17 @@ notorious **777**, instead assigning them on a need-to-know basis. .. code-block:: console # :nxt_hint:`useradd ` -M app_user + + .. code-block:: console + # groupadd app_group + + .. code-block:: console + # :nxt_hint:`usermod ` -L app_user + + .. code-block:: console + # :nxt_hint:`usermod ` -a -G app_group app_user Even if you run a single app, this helps if you add more apps or need to @@ -299,6 +323,8 @@ notorious **777**, instead assigning them on a need-to-know basis. :nxt_hint:`drwxr-xr-x ` some_user some_group path + .. code-block:: console + # ls -l /path/ :nxt_hint:`drwxr-x--- ` some_user some_group to @@ -324,8 +350,17 @@ notorious **777**, instead assigning them on a need-to-know basis. .. code-block:: console # :nxt_hint:`chown ` -R app_user:app_group :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + # :nxt_hint:`chown ` -R app_user:app_group :nxt_ph:`/path/to/static/app/files/ ` + + .. code-block:: console + # find :nxt_ph:`/path/to/app/ ` -type d -exec :nxt_hint:`chmod ` u=rx,g=rx,o= {} \; + + .. code-block:: console + # find :nxt_ph:`/path/to/static/app/files/ ` -type d -exec :nxt_hint:`chmod ` u=rx,g=rx,o= {} \; #. If the app needs to update specific directories or files, make sure @@ -356,6 +391,9 @@ notorious **777**, instead assigning them on a need-to-know basis. .. code-block:: console # find :nxt_ph:`/path/to/app/code/ ` -type f -exec :nxt_hint:`chmod ` u=r,g=r,o= {} \; + + .. code-block:: console + # find :nxt_ph:`/path/to/static/app/files/ ` -type f -exec :nxt_hint:`chmod ` u=r,g=r,o= {} \; #. For :ref:`external ` apps, additionally make the app code or @@ -364,6 +402,9 @@ notorious **777**, instead assigning them on a need-to-know basis. .. code-block:: console # find :nxt_ph:`/path/to/app/ ` -type f -exec :nxt_hint:`chmod ` u=rx,g=rx,o= {} \; + + .. code-block:: console + # find :nxt_ph:`/path/to/static/app/files/ ` -type f -exec :nxt_hint:`chmod ` u=r,g=r,o= {} \; #. To run a single app, :doc:`configure <../configuration/index>` Unit as follows: @@ -688,6 +729,8 @@ disk space. # :nxt_hint:`chown ` log_user:log_group :nxt_ph:`/path/to/unit.log ` + .. code-block:: console + # :nxt_hint:`curl ` -X PUT -d '":nxt_ph:`/path/to/access.log `"' \ --unix-socket :nxt_ph:`/path/to/control.unit.sock ` \ http://localhost/config/access_log @@ -696,6 +739,8 @@ disk space. "success": "Reconfiguration done." } + .. code-block:: console + # :nxt_hint:`chown ` log_user:log_group :nxt_ph:`/path/to/access.log ` If you change the log file ownership, adjust your :program:`logrotate` diff --git a/source/howto/source.rst b/source/howto/source.rst index c7c1cf73..e3c1d781 100644 --- a/source/howto/source.rst +++ b/source/howto/source.rst @@ -31,17 +31,47 @@ revision numbers, respectively); omit the packages you won't use. .. code-block:: console # apt install build-essential + + .. code-block:: console + # apt install golang + + .. code-block:: console + # apt install curl && \ curl -sL https://deb.nodesource.com/setup_:nxt_ph:`VERSION `.x | bash - && \ apt install nodejs + + .. code-block:: console + # npm install -g node-gyp + + .. code-block:: console + # apt install php-dev libphp-embed + + .. code-block:: console + # apt install libperl-dev + + .. code-block:: console + # apt install python:nxt_ph:`X `-dev + + .. code-block:: console + # apt install ruby-dev ruby-rack + + .. code-block:: console + # apt install openjdk-:nxt_ph:`X `-jdk + + .. code-block:: console + # apt install libssl-dev + + .. code-block:: console + # apt install libpcre2-dev @@ -50,17 +80,47 @@ revision numbers, respectively); omit the packages you won't use. .. code-block:: console # yum install gcc make + + .. code-block:: console + # yum install golang + + .. code-block:: console + # yum install curl && \ curl -sL https://rpm.nodesource.com/setup_:nxt_ph:`VERSION `.x | bash - && \ yum install nodejs + + .. code-block:: console + # npm install -g node-gyp + + .. code-block:: console + # yum install php-devel php-embedded + + .. code-block:: console + # yum install perl-devel perl-libs + + .. code-block:: console + # yum install python:nxt_ph:`X `-devel + + .. code-block:: console + # yum install ruby-devel rubygem-rack + + .. code-block:: console + # yum install java-:nxt_ph:`X.Y.Z `-openjdk-devel + + .. code-block:: console + # yum install openssl-devel + + .. code-block:: console + # yum install pcre2-devel @@ -71,14 +131,41 @@ revision numbers, respectively); omit the packages you won't use. .. code-block:: console # cd /usr/ports/lang/go/ && make install clean + + .. code-block:: console + # cd /usr/ports/www/node/ && make install clean + + .. code-block:: console + # cd /usr/ports/www/npm/ && make install clean && npm i -g node-gyp + + .. code-block:: console + # cd /usr/ports/lang/php:nxt_ph:`XY `/ && make install clean + + .. code-block:: console + # cd /usr/ports/lang/perl:nxt_ph:`X.Y `/ && make install clean + + .. code-block:: console + # cd /usr/ports/lang/python/ && make install clean + + .. code-block:: console + # cd /usr/ports/lang/ruby:nxt_ph:`XY `/ && make install clean + + .. code-block:: console + # cd /usr/ports/java/openjdk:nxt_ph:`X `/ && make install clean + + .. code-block:: console + # cd /usr/ports/security/openssl/ && make install clean + + .. code-block:: console + # cd /usr/ports/devel/pcre2/ && make install clean Packages: @@ -86,13 +173,37 @@ revision numbers, respectively); omit the packages you won't use. .. code-block:: console # pkg install go + + .. code-block:: console + # pkg install node && pkg install npm && npm i -g node-gyp + + .. code-block:: console + # pkg install php:nxt_ph:`XY ` + + .. code-block:: console + # pkg install perl:nxt_ph:`X ` + + .. code-block:: console + # pkg install python + + .. code-block:: console + # pkg install ruby:nxt_ph:`XY ` + + .. code-block:: console + # pkg install openjdk:nxt_ph:`X ` + + .. code-block:: console + # pkg install openssl + + .. code-block:: console + # pkg install pcre2 @@ -101,11 +212,29 @@ revision numbers, respectively); omit the packages you won't use. .. code-block:: console # pkg install gcc + + .. code-block:: console + # pkg install golang + + .. code-block:: console + # pkg install php-:nxt_ph:`XY ` + + .. code-block:: console + # pkg install ruby + + .. code-block:: console + # pkg install jdk-:nxt_ph:`X ` + + .. code-block:: console + # pkg install openssl + + .. code-block:: console + # pkg install pcre Also, use :program:`gmake` instead of :program:`make` when :ref:`building @@ -124,7 +253,13 @@ revision numbers, respectively); omit the packages you won't use. .. code-block:: console $ git clone https://github.com/nginx/njs.git + + .. code-block:: console + $ cd njs + + .. code-block:: console + $ git checkout -b 0.8.2 0.8.2 Next, configure and build the :program:`njs` binaries. Make sure to use the @@ -179,6 +314,9 @@ revision numbers, respectively); omit the packages you won't use. .. code-block:: console $ cd .. + + .. code-block:: console + $ wget -O- https://github.com/bytecodealliance/wasmtime/releases/download/v12.0.0/wasmtime-v12.0.0-x86_64-linux-c-api.tar.xz \ | tar Jxf - # Unpacks to the current directory @@ -397,7 +535,13 @@ structure `: .. code-block:: console $ ./configure --control=127.0.0.1:8080 + + .. code-block:: console + $ ./configure --control=[::1]:8080 + + .. code-block:: console + $ ./configure --control=unix:/path/to/control.unit.sock # Note the unix: prefix .. warning:: @@ -808,6 +952,9 @@ To build and install Unit's executables and language modules that you have .. code-block:: console $ make + +.. code-block:: console + # make install Mind that **make install** requires setting up Unit's :ref:`directory @@ -818,7 +965,13 @@ To run Unit from the build directory tree without installing: .. code-block:: console $ ./configure --prefix=./build + +.. code-block:: console + $ make + +.. code-block:: console + $ ./build/sbin/unitd You can also build and install language modules individually; the specific @@ -842,8 +995,10 @@ configuration, run :command:`make ` and :command:`make .. code-block:: console $ make :nxt_hint:`perl-5.20 ` - # make :nxt_hint:`perl-5.20 `-install +.. code-block:: console + + # make :nxt_hint:`perl-5.20 `-install .. _source-bld-src-ext: @@ -857,6 +1012,9 @@ configuration, run :command:`make -install` and :command:`make .. code-block:: console # make :nxt_hint:`go `-install + +.. code-block:: console + # make :nxt_hint:`node `-install .. note:: @@ -887,9 +1045,17 @@ If you customized the executable pathname with :option:`!--go` or .. code-block:: console $ ./configure nodejs --node=:nxt_hint:`/usr/local/bin/node8.12 ` + +.. code-block:: console + # make :nxt_hint:`/usr/local/bin/node8.12 `-install +.. code-block:: console + $ ./configure go --go=:nxt_hint:`/usr/local/bin/go1.7 ` + +.. code-block:: console + # make :nxt_hint:`/usr/local/bin/go1.7 `-install @@ -941,7 +1107,13 @@ counterparts, see :ref:`here `. .. code-block:: console # unitd --control 127.0.0.1:8080 + + .. code-block:: console + # unitd --control [::1]:8080 + + .. code-block:: console + # unitd --control :nxt_hint:`unix:/path/to/control.unit.sock ` * - **--control-mode** diff --git a/source/howto/springboot.rst b/source/howto/springboot.rst index 904aabf6..1d0d6058 100644 --- a/source/howto/springboot.rst +++ b/source/howto/springboot.rst @@ -65,6 +65,9 @@ To run apps based on the `Spring Boot .. code-block:: console $ cd :nxt_ph:`/path/to/app/ `demo/ + + .. code-block:: console + $ ./gradlew bootWar If you chose `Maven `__: @@ -72,6 +75,9 @@ To run apps based on the `Spring Boot .. code-block:: console $ cd :nxt_ph:`/path/to/app/ `demo/ + + .. code-block:: console + $ ./mvnw package .. note:: diff --git a/source/howto/starlette.rst b/source/howto/starlette.rst index e465497c..3607e743 100644 --- a/source/howto/starlette.rst +++ b/source/howto/starlette.rst @@ -115,10 +115,14 @@ framework using Unit: Hello, world! + .. code-block:: console + $ curl http://localhost/user/me Hello, John Doe! + .. code-block:: console + $ wscat -c ws://localhost/ws Connected (press CTRL+C to quit) diff --git a/source/howto/symfony.rst b/source/howto/symfony.rst index 26fe5f25..a9a7c1f6 100644 --- a/source/howto/symfony.rst +++ b/source/howto/symfony.rst @@ -16,6 +16,9 @@ To run apps built with the `Symfony `_ framework using Unit .. code-block:: console $ cd :nxt_ph:`/path/to/ ` + + .. code-block:: console + $ symfony new --demo :nxt_ph:`app ` This creates the app's directory tree at **/path/to/app/**. Its diff --git a/source/howto/trac.rst b/source/howto/trac.rst index 4c04de14..d82183ef 100644 --- a/source/howto/trac.rst +++ b/source/howto/trac.rst @@ -30,8 +30,17 @@ Unit: .. code-block:: console $ mkdir -p :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ virtualenv venv + + .. code-block:: console + $ source venv/bin/activate #. Next, `install Trac `_ and its @@ -41,14 +50,38 @@ Unit: .. code-block:: console $ pip install Trac + + .. code-block:: console + $ pip install babel docutils genshi \ pygments pytz textile # optional dependencies + + .. code-block:: console + $ mkdir :nxt_ph:`static/ ` # will store Trac's /chrome/ tree + + .. code-block:: console + $ mkdir :nxt_ph:`trac_env/ ` + + .. code-block:: console + $ trac-admin trac_env/ initenv # initialize Trac environment + + .. code-block:: console + $ trac-admin trac_env/ deploy static/ # extract Trac's static files + + .. code-block:: console + $ mv static/htdocs static/chrome # align static file paths + + .. code-block:: console + $ rm -rf static/cgi-bin/ # remove unneeded files + + .. code-block:: console + $ deactivate #. Unit :ref:`uses WSGI ` to run Python apps, so a diff --git a/source/howto/yii.rst b/source/howto/yii.rst index c0fe9960..7f1a2705 100644 --- a/source/howto/yii.rst +++ b/source/howto/yii.rst @@ -26,6 +26,9 @@ versions 1.1 or 2.0 using Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/ ` + + .. code-block:: console + $ composer create-project --prefer-dist yiisoft/yii2-app-basic :nxt_ph:`app ` This creates the app's directory tree at **/path/to/app/**. @@ -130,6 +133,9 @@ versions 1.1 or 2.0 using Unit: .. code-block:: console $ git clone git@github.com:yiisoft/yii.git :nxt_ph:`/path/to/yii1.1/ ` + + .. code-block:: console + $ :nxt_ph:`/path/to/yii1.1/ `framework/yiic webapp :nxt_ph:`/path/to/app/ ` This creates the app's directory tree at **/path/to/app/**. diff --git a/source/howto/zope.rst b/source/howto/zope.rst index 293198c6..bd4c9001 100644 --- a/source/howto/zope.rst +++ b/source/howto/zope.rst @@ -29,9 +29,21 @@ Unit: .. code-block:: console $ pip install -U pip wheel zc.buildout + + .. code-block:: console + $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ wget https://pypi.org/packages/source/Z/Zope/Zope-:nxt_ph:`A.B.C `.tar.gz + + .. code-block:: console + $ tar xfvz Zope-:nxt_ph:`A.B.C `.tar.gz :nxt_hint:`--strip-components `=1 + + .. code-block:: console + $ buildout Next, add a new configuration file named @@ -107,11 +119,26 @@ Unit: .. code-block:: console $ cd :nxt_ph:`/path/to/app/ ` + + .. code-block:: console + $ :nxt_hint:`python3 --version ` Python :nxt_hint:`3.Y.Z ` + + .. code-block:: console + $ python3 -m venv :nxt_hint:`venv ` + + .. code-block:: console + $ source venv/bin/activate + + .. code-block:: console + $ pip install 'zope[wsgi]' + + .. code-block:: console + $ deactivate .. warning:: diff --git a/source/installation.rst b/source/installation.rst index d07e605e..edce9d63 100644 --- a/source/installation.rst +++ b/source/installation.rst @@ -149,6 +149,9 @@ at the `npm `_ registry. .. code-block:: console $ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit + + .. code-block:: console + # ./setup-unit repo-config Use it at your discretion; @@ -188,8 +191,14 @@ Amazon Linux .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc17 unit-perl \ unit-php unit-python39 unit-python311 unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -229,8 +238,14 @@ Amazon Linux .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-perl \ unit-php unit-python27 unit-python37 unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -276,8 +291,14 @@ Amazon Linux .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-perl unit-php \ unit-python27 unit-python34 unit-python35 unit-python36 + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -334,9 +355,18 @@ Debian .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-jsc17 unit-perl \ unit-php unit-python3.11 unit-ruby unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup @@ -385,9 +415,18 @@ Debian .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-jsc11 unit-perl \ unit-php unit-python2.7 unit-python3.9 unit-ruby unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup @@ -442,9 +481,18 @@ Debian .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-jsc11 unit-perl \ unit-php unit-python2.7 unit-python3.7 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -498,9 +546,18 @@ Debian .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-jsc8 unit-perl \ unit-php unit-python2.7 unit-python3.5 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -549,8 +606,14 @@ Fedora .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-jsc11 unit-perl \ unit-php unit-python311 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -590,8 +653,14 @@ Fedora .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-jsc11 unit-perl \ unit-php unit-python311 unit-ruby unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -637,8 +706,14 @@ Fedora .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-jsc11 unit-perl \ unit-php unit-python39 unit-python310 unit-ruby unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -684,8 +759,14 @@ Fedora .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-jsc11 unit-perl \ unit-php unit-python39 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -731,8 +812,14 @@ Fedora .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-jsc11 unit-perl \ unit-php unit-python38 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -779,8 +866,14 @@ Fedora .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-jsc11 unit-perl \ unit-php unit-python27 unit-python37 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -826,8 +919,14 @@ Fedora .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-perl \ unit-php unit-python27 unit-python37 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -877,8 +976,14 @@ RHEL and derivatives .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-go unit-jsc8 unit-jsc11 \ unit-perl unit-php unit-python39 unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -918,8 +1023,14 @@ RHEL and derivatives .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-jsc11 \ unit-perl unit-php unit-python27 unit-python36 unit-python38 unit-python39 unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -963,8 +1074,14 @@ RHEL and derivatives .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-jsc11 \ unit-perl unit-php unit-python27 unit-python36 + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1010,8 +1127,14 @@ RHEL and derivatives .. code-block:: console # yum install unit + + .. code-block:: console + # yum install :nxt_hint:`unit-devel ` unit-jsc8 unit-perl \ unit-php unit-python + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1077,9 +1200,18 @@ Ubuntu .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-go unit-jsc11 unit-jsc17 unit-jsc18 unit-jsc19 unit-jsc20 \ unit-perl unit-php unit-python3.11 unit-ruby unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1133,9 +1265,18 @@ Ubuntu .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-go unit-jsc11 unit-jsc17 unit-jsc18 unit-jsc19 \ unit-perl unit-php unit-python2.7 unit-python3.10 unit-ruby unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1183,9 +1324,18 @@ Ubuntu .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-go unit-jsc11 unit-jsc16 unit-jsc17 unit-jsc18 \ unit-perl unit-php unit-python2.7 unit-python3.10 unit-ruby unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1239,9 +1389,18 @@ Ubuntu .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-jsc11 unit-jsc16 unit-jsc17 unit-jsc18 \ unit-perl unit-php unit-python2.7 unit-python3.9 unit-python3.10 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1295,7 +1454,13 @@ Ubuntu .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-jsc11 unit-jsc15 unit-jsc16 unit-jsc17 \ unit-perl unit-php unit-python2.7 unit-python3.9 unit-ruby # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup @@ -1351,9 +1516,18 @@ Ubuntu .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-jsc11 unit-jsc13 unit-jsc14 unit-jsc15 \ unit-perl unit-php unit-python3.8 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1401,9 +1575,18 @@ Ubuntu .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-jsc11 unit-perl \ unit-php unit-python2.7 unit-python3.8 unit-ruby unit-wasm + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1457,9 +1640,18 @@ Ubuntu .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-jsc11 unit-perl \ unit-php unit-python2.7 unit-python3.7 unit-python3.8 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1513,9 +1705,18 @@ Ubuntu .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-jsc8 unit-jsc11 unit-perl \ unit-php unit-python2.7 unit-python3.6 unit-python3.7 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1569,9 +1770,18 @@ Ubuntu .. code-block:: console # apt update + + .. code-block:: console + # apt install unit + + .. code-block:: console + # apt install :nxt_hint:`unit-dev ` unit-jsc8 unit-perl unit-php \ unit-python2.7 unit-python3.5 unit-ruby + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1619,7 +1829,13 @@ macOS .. code-block:: console $ brew install unit-java unit-perl unit-php unit-python unit-python3 unit-ruby + + .. code-block:: console + # pkill unitd # Stop Unit + + .. code-block:: console + # unitd # Start Unit to pick up any changes in language module setup Runtime details: @@ -1642,6 +1858,9 @@ macOS .. code-block:: console $ export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES + + .. code-block:: console + $ sudo --preserve-env=OBJC_DISABLE_INITIALIZE_FORK_SAFETY :nxt_ph:`/path/to/unitd ` ... @@ -1721,7 +1940,13 @@ make sure to update the module as well: .. code-block:: console $ nvm install 18 + + .. code-block:: console + $ nvm install 16 + + .. code-block:: console + $ nvm use 18 Now using node :nxt_hint:`v18.12.1 ` (npm v8.19.2) @@ -1739,11 +1964,22 @@ make sure to update the module as well: .. code-block:: console $ git clone https://github.com/nginx/unit + + .. code-block:: console + $ cd unit + + .. code-block:: console + $ pwd :nxt_hint:`/home/user/unit ` + .. code-block:: console + $ ./configure + + .. code-block:: console + $ ./configure nodejs configuring nodejs module @@ -1762,6 +1998,8 @@ make sure to update the module as well: $ CPPFLAGS="-I/home/user/unit/include/" LDFLAGS="-L/home/user/unit/lib/" \ make node-install + .. code-block:: console + $ npm list -g /home/vagrant/.nvm/versions/node/v18.12.1/lib @@ -1873,7 +2111,13 @@ Community Repositories .. code-block:: console # apk update + + .. code-block:: console + # apk upgrade + + .. code-block:: console + # apk add unit To install service manager files @@ -1882,6 +2126,9 @@ Community Repositories .. code-block:: console # apk add unit-openrc unit-perl unit-php7 unit-python3 unit-ruby + + .. code-block:: console + # service unit restart # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -1901,8 +2148,17 @@ Community Repositories - .. code-block:: console # :nxt_hint:`service unit enable ` + + .. code-block:: console + # :nxt_hint:`service unit restart ` + + .. code-block:: console + # :nxt_hint:`service unit stop ` + + .. code-block:: console + # :nxt_hint:`service unit disable ` @@ -1916,8 +2172,17 @@ Community Repositories .. code-block:: console # apt-get update + + .. code-block:: console + # apt-get install unit + + .. code-block:: console + # apt-get install unit-perl unit-php unit-python3 unit-ruby + + .. code-block:: console + # service unit restart # Necessary for Unit to pick up any changes in language module setup Versions of these packages @@ -1942,8 +2207,17 @@ Community Repositories - .. code-block:: console # :nxt_hint:`service unit enable ` + + .. code-block:: console + # :nxt_hint:`service unit restart ` + + .. code-block:: console + # :nxt_hint:`service unit stop ` + + .. code-block:: console + # :nxt_hint:`service unit disable ` @@ -1988,8 +2262,17 @@ Community Repositories - .. code-block:: console # :nxt_hint:`systemctl enable unit ` + + .. code-block:: console + # :nxt_hint:`systemctl restart unit ` + + .. code-block:: console + # :nxt_hint:`systemctl stop unit ` + + .. code-block:: console + # :nxt_hint:`systemctl disable unit ` @@ -2003,13 +2286,22 @@ Community Repositories .. code-block:: console # pkg install -y unit + + .. code-block:: console + # pkg install -y :nxt_hint:`libunit ` + + .. code-block:: console + # pkg install -y unit-java8 \ unit-perl5.36 \ unit-php81 unit-php82 unit-php83 \ unit-python39 \ unit-ruby3.2 \ unit-wasm + + .. code-block:: console + # service unitd restart # Necessary for Unit to pick up any changes in language module setup To install Unit from @@ -2035,7 +2327,13 @@ Community Repositories .. code-block:: console # cd /usr/ports/www/unit/ + + .. code-block:: console + # make + + .. code-block:: console + # make install Repeat the steps for the other ports you need: @@ -2081,8 +2379,17 @@ Community Repositories - .. code-block:: console # :nxt_hint:`service unitd enable ` + + .. code-block:: console + # :nxt_hint:`service unitd restart ` + + .. code-block:: console + # :nxt_hint:`service unitd stop ` + + .. code-block:: console + # :nxt_hint:`service unitd disable ` @@ -2098,6 +2405,9 @@ Community Repositories .. code-block:: console # emerge --sync + + .. code-block:: console + # emerge www-servers/nginx-unit To install specific language modules and features, @@ -2122,8 +2432,17 @@ Community Repositories - .. code-block:: console # :nxt_hint:`rc-update add nginx-unit ` + + .. code-block:: console + # :nxt_hint:`rc-service nginx-unit restart ` + + .. code-block:: console + # :nxt_hint:`rc-service nginx-unit stop ` + + .. code-block:: console + # :nxt_hint:`rc-update del nginx-unit ` @@ -2138,11 +2457,20 @@ Community Repositories .. code-block:: console # pkg_add unit + + .. code-block:: console + # pkg_add :nxt_hint:`libunit ` + + .. code-block:: console + # pkg_add unit-perl \ unit-python2.7 \ unit-python3.8 unit-python3.9 unit-python3.10 unit-python3.11 unit-python3.12 \ unit-ruby31 unit-ruby32 unit-ruby33 + + .. code-block:: console + # service unit restart # Necessary for Unit to pick up any changes in language module setup To build Unit manually, @@ -2158,6 +2486,9 @@ Community Repositories .. code-block:: console # cd /usr/pkgsrc/www/unit/ + + .. code-block:: console + # make build install Repeat the steps for the other packages you need: @@ -2218,6 +2549,9 @@ Community Repositories .. code-block:: console # :nxt_hint:`service unit restart ` + + .. code-block:: console + # :nxt_hint:`service unit stop ` To enable or disable Unit's automatic startup, @@ -2288,8 +2622,17 @@ Community Repositories .. code-block:: console # :nxt_hint:`systemctl enable unit ` + + .. code-block:: console + # :nxt_hint:`systemctl restart unit ` + + .. code-block:: console + # :nxt_hint:`systemctl stop unit ` + + .. code-block:: console + # :nxt_hint:`systemctl disable unit ` @@ -2303,14 +2646,41 @@ Community Repositories .. code-block:: console # pkg_add unit + + .. code-block:: console + # pkg_add unit-perl + + .. code-block:: console + # pkg_add unit-php74 + + .. code-block:: console + # pkg_add unit-php80 + + .. code-block:: console + # pkg_add unit-php81 + + .. code-block:: console + # pkg_add unit-php82 + + .. code-block:: console + # pkg_add unit-php83 + + .. code-block:: console + # pkg_add unit-python + + .. code-block:: console + # pkg_add unit-ruby + + .. code-block:: console + # rcctl restart unit # Necessary for Unit to pick up any changes in language module setup To install Unit from @@ -2321,6 +2691,9 @@ Community Repositories .. code-block:: console $ cd /usr/ + + .. code-block:: console + $ cvs -d anoncvs@anoncvs.spacehopper.org:/cvs checkout -P ports Next, browse to the port path to build and install Unit: @@ -2328,7 +2701,13 @@ Community Repositories .. code-block:: console $ cd /usr/ports/www/unit/ + + .. code-block:: console + $ make + + .. code-block:: console + # make install This also installs the language modules for Perl, PHP, Python, and Ruby; @@ -2354,11 +2733,21 @@ Community Repositories - **_unit** * - Startup and shutdown + - .. code-block:: console # :nxt_hint:`rcctl enable unit ` + + .. code-block:: console + # :nxt_hint:`rcctl restart unit ` + + .. code-block:: console + # :nxt_hint:`rcctl stop unit ` + + .. code-block:: console + # :nxt_hint:`rcctl disable unit ` @@ -2387,6 +2776,9 @@ Community Repositories php54-unit-php php55-unit-php php56-unit-php \ php70-unit-php php71-unit-php php72-unit-php php73-unit-php php74-unit-php \ php80-unit-php php81-unit-php php82-unit-php + + .. code-block:: console + # systemctl restart unit # Necessary for Unit to pick up any changes in language module setup Runtime details: @@ -2406,8 +2798,17 @@ Community Repositories - .. code-block:: console # :nxt_hint:`systemctl enable unit ` + + .. code-block:: console + # :nxt_hint:`systemctl restart unit ` + + .. code-block:: console + # :nxt_hint:`systemctl stop unit ` + + .. code-block:: console + # :nxt_hint:`systemctl disable unit ` @@ -2511,9 +2912,21 @@ come in several language-specific flavors: .. subs-code-block:: console $ git clone https://github.com/nginx/unit + + .. code-block:: console + $ cd unit + + .. code-block:: console + $ git checkout |version| # Optional; use to choose a specific Unit version + + .. code-block:: console + $ cd pkg/docker/ + + .. code-block:: console + $ make build-:nxt_ph:`python3.10 ` VERSIONS_:nxt_ph:`python `=:nxt_ph:`3.10 ` For details, see the @@ -2567,6 +2980,9 @@ You can obtain the images from these sources: .. code-block:: console $ docker pull unit::nxt_ph:`TAG ` + + .. code-block:: console + $ docker run -d unit::nxt_ph:`TAG ` @@ -2579,6 +2995,9 @@ You can obtain the images from these sources: .. code-block:: console $ docker pull public.ecr.aws/nginx/unit::nxt_ph:`TAG ` + + .. code-block:: console + $ docker run -d public.ecr.aws/nginx/unit::nxt_ph:`TAG ` @@ -2596,10 +3015,18 @@ You can obtain the images from these sources: .. subs-code-block:: console $ curl -O https://packages.nginx.org/unit/docker/1.29.1/nginx-unit-:nxt_ph:`TAG `.tar.gz + + .. code-block:: console + $ curl -O https://packages.nginx.org/unit/docker/1.29.1/nginx-unit-:nxt_ph:`TAG `.tar.gz.sha512 + + .. code-block:: console + $ sha512sum -c nginx-unit-:nxt_ph:`TAG `.tar.gz.sha512 nginx-unit-:nxt_ph:`TAG `.tar.gz: OK + .. code-block:: console + $ docker load < nginx-unit-:nxt_ph:`TAG `.tar.gz Runtime details: @@ -2722,8 +3149,17 @@ or as a tarball. .. subs-code-block:: console $ git clone https://github.com/nginx/unit # Latest updates to the repository + + .. subs-code-block:: console + $ # -- or -- + + .. subs-code-block:: console + $ git clone -b |version| https://github.com/nginx/unit # Specific version tag; see https://github.com/nginx/unit/tags + + .. subs-code-block:: console + $ cd unit @@ -2732,7 +3168,13 @@ or as a tarball. .. subs-code-block:: console $ curl -O https://sources.nginx.org/unit/unit-|version|.tar.gz + + .. subs-code-block:: console + $ tar xzf unit-|version|.tar.gz + + .. subs-code-block:: console + $ cd unit-|version| To build Unit and specific language modules from these sources, diff --git a/source/news/2022/unit-1.29.0-released.rst b/source/news/2022/unit-1.29.0-released.rst index 71861398..66c1d4e6 100644 --- a/source/news/2022/unit-1.29.0-released.rst +++ b/source/news/2022/unit-1.29.0-released.rst @@ -131,8 +131,17 @@ Installing and running Unit on a typical Linux system is now as simple as this: .. code-block:: console $ wget https://unit.nginx.org/_downloads/setup-unit && chmod +x setup-unit + +.. code-block:: console + # ./setup-unit repo-config + +.. code-block:: console + # apt install unit || yum install unit + +.. code-block:: console + # ./setup-unit welcome The :program:`setup-unit` tool has other useful functions you can explore by @@ -155,6 +164,9 @@ reads and updates the entire configuration: .. code-block:: console $ unitc /config + +.. code-block:: console + $ cat conf.json | unitc /config You can find these tools and their corresponding documentation in the diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index be4fc344..7e5442dc 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -261,6 +261,9 @@ such as **unit-dbg**. .. code-block:: console # systemctl daemon-reload + + .. code-block:: console + # systemctl restart unit.service After a crash, @@ -273,6 +276,8 @@ such as **unit-dbg**. TIME PID UID GID SIG COREFILE EXE Mon 2020-07-27 11:05:40 GMT 1157 0 0 11 present /usr/sbin/unitd + .. code-block:: console + # ls -al /var/lib/systemd/coredump/ # default, see also /etc/systemd/coredump.conf and /etc/systemd/coredump.conf.d/*.conf ... @@ -301,7 +306,13 @@ such as **unit-dbg**. .. code-block:: console # ulimit -c unlimited + + .. code-block:: console + # cd :nxt_ph:`/path/to/unit/ ` + + .. code-block:: console + # sbin/unitd # or sbin/unitd-debug After a crash, @@ -336,6 +347,9 @@ such as **unit-dbg**. .. code-block:: console # sysctl kern.coredump=1 + + .. code-block:: console + # sysctl kern.corefile=/path/to/core/files/%N.core Next, restart Unit @@ -351,6 +365,9 @@ such as **unit-dbg**. .. code-block:: console # cd :nxt_ph:`/path/to/unit/ ` + + .. code-block:: console + # sbin/unitd After a crash, diff --git a/source/unitctl.rst b/source/unitctl.rst index 399ef125..cb01d8df 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -363,8 +363,17 @@ use standard output with **-f -**, as shown in the examples below: .. code-block:: console $ unitctl export -f config.tar + +.. code-block:: console + $ unitctl export -f - + +.. code-block:: console + $ unitctl export -f - | tar xf - config.json + +.. code-block:: console + $ unitctl export -f - > config.tar .. warning:: From 796f7ea93b445bf8d91dcc4ee4ff907471daf8f5 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 16 Sep 2024 18:02:23 +0100 Subject: [PATCH 35/45] docs: update release 1.33 date --- source/conf.py | 2 +- source/news/2024/index.rst | 2 +- source/news/2024/unit-1.33.0-released.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/conf.py b/source/conf.py index b4741340..480330be 100644 --- a/source/conf.py +++ b/source/conf.py @@ -6,7 +6,7 @@ author = 'NGINX, Inc.' copyright = '2017-2024' version = '1.33.0' -release_date = 'Aug 29, 2024' +release_date = 'Sep 17, 2024' release = version needs_sphinx = '6.2' diff --git a/source/news/2024/index.rst b/source/news/2024/index.rst index 3171d7a5..182f84ad 100644 --- a/source/news/2024/index.rst +++ b/source/news/2024/index.rst @@ -10,7 +10,7 @@ News archive for the year 2024. :email: unit-owner@nginx.org :title: Unit 1.33.0 Released :url: news/2024/unit-1.33.0-released - :date: 2024-08-29 + :date: 2024-09-17 .. nxt_news_entry:: :author: Unit Team diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 1010a451..5b1ad8db 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -160,7 +160,7 @@ Full Changelog .. code-block:: none - Changes with Unit 1.33.0 29 Aug 2024 + Changes with Unit 1.33.0 17 Sep 2024 *) Feature: show list of loaded language modules in the /status endpoint. From 48bf2adaca46b7a06608b9b4f78f04456ec41edf Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 16 Sep 2024 18:06:15 +0100 Subject: [PATCH 36/45] docs: update factory description --- source/news/2024/unit-1.33.0-released.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 5b1ad8db..d0bcf42e 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -32,7 +32,9 @@ This release introduces three new configuration options: #. **factory** - This can be set under '/applications//factory' + This option can be set under '/applications//factory' and is specific to + Python applications. This allows you to enable the `Application factories` + feature of Python. This option is a boolean value. If set to 'true', Unit treats 'callable' as a factory. From 09c5995dd25908047b0865661614c4bce39d6737 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 16 Sep 2024 19:23:15 +0100 Subject: [PATCH 37/45] docs: add unitctl note --- source/news/2024/unit-1.33.0-released.rst | 6 ++++++ source/unitctl.rst | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index d0bcf42e..2f3bf5a1 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -50,6 +50,12 @@ unitctl CLI tool :ref:`unitctl ` is a Rust-based CLI tool that allows you to deploy, manage, and configure Unit in your environment. +.. note:: + + This is a "Technical Preview" release of **unitctl**. We welcome feedback and + suggestions for this early access version. It is provided to test its features + and should not be used in production environments. + **************************** Chunked request body support **************************** diff --git a/source/unitctl.rst b/source/unitctl.rst index cb01d8df..57b70538 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -8,6 +8,12 @@ CLI (unitctl) ############# +.. note:: + + This is a "Technical Preview" release of **unitctl**. We welcome feedback and + suggestions for this early access version. It is provided to test its features + and should not be used in production environments. + Unit provides a `Rust SDK `_ to interact with its :ref:`control API `, and a command line interface (unitctl) that exposes the functionality provided by the SDK. From 8249097abb9d46fe4422d15053f7ad225a662f3d Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 16 Sep 2024 19:27:41 +0100 Subject: [PATCH 38/45] docs: note updates --- source/unitctl.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/unitctl.rst b/source/unitctl.rst index 57b70538..c2dd58ea 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -10,9 +10,9 @@ CLI (unitctl) .. note:: - This is a "Technical Preview" release of **unitctl**. We welcome feedback and - suggestions for this early access version. It is provided to test its features - and should not be used in production environments. + **unitctl** is currently being provided as a "Technical Preview". We welcome + feedback and suggestions for this early access version. It is provided to test + its features and should not be used in production environments. Unit provides a `Rust SDK `_ to interact with its :ref:`control API `, and a command line From 70bc45319fcd3459e4cb4d9d42a63ef27c7b1530 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Tue, 17 Sep 2024 11:34:29 +0100 Subject: [PATCH 39/45] 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 c2dd58ea..637ce134 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -164,7 +164,7 @@ host network. List and restart running apps +++++++++++++++++++++++++++++ -The **app** command lets you list and restart active applications. +The **apps** command lets you list and restart active applications. Options ------- From 3be24ca6142103a69e1bd47b428bf8926d7bface Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Tue, 17 Sep 2024 11:34:52 +0100 Subject: [PATCH 40/45] 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 637ce134..39e29405 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -180,7 +180,7 @@ The **app** command has the following options: * - **list** - List all active applications - * - **reload ** + * - **restart ** - Restart the specified application To list active applications, run: From f944bc423439df68968b082141c06e9f7eb63275 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Tue, 17 Sep 2024 15:09:40 +0100 Subject: [PATCH 41/45] 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 39e29405..e4ee4747 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -52,7 +52,7 @@ The unitctl CLI offers several commands to interact with Unit. Here are the avai * - **instances** - List all running Unit processes - * - **app** + * - **apps** - List and restart active applications * - **edit** From 9a7658d520f63dfc12c96bf2a013f990d07b27f9 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Tue, 17 Sep 2024 15:09:49 +0100 Subject: [PATCH 42/45] 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 e4ee4747..f3f014a5 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -187,7 +187,7 @@ To list active applications, run: .. code-block:: console - $ unitctl app list + $ unitctl apps list { "wasm": { "type": "wasm-wasi-component", From dc4070bc498148b7afe0e924c8b058bf283747b4 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Tue, 17 Sep 2024 15:09:56 +0100 Subject: [PATCH 43/45] 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 f3f014a5..14e7e6bd 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -199,7 +199,7 @@ To restart an application, run: .. code-block:: console - $ unitctl app reload wasm + $ unitctl apps restart wasm { "success": "Ok" } From 4c6335302fb0644545294e330191660068bb4034 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Date: Tue, 17 Sep 2024 15:10:01 +0100 Subject: [PATCH 44/45] 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 14e7e6bd..a654ef19 100644 --- a/source/unitctl.rst +++ b/source/unitctl.rst @@ -169,7 +169,7 @@ The **apps** command lets you list and restart active applications. Options ------- -The **app** command has the following options: +The **apps** command has the following options: .. list-table:: :header-rows: 1 From 43dfe74d7bf57bd71f1f4b36cf673efb7f37ca31 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 18 Sep 2024 14:59:09 +0100 Subject: [PATCH 45/45] docs: update dates --- source/conf.py | 2 +- source/news/2024/index.rst | 2 +- source/news/2024/unit-1.33.0-released.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/conf.py b/source/conf.py index 480330be..829b3a29 100644 --- a/source/conf.py +++ b/source/conf.py @@ -6,7 +6,7 @@ author = 'NGINX, Inc.' copyright = '2017-2024' version = '1.33.0' -release_date = 'Sep 17, 2024' +release_date = 'Sep 18, 2024' release = version needs_sphinx = '6.2' diff --git a/source/news/2024/index.rst b/source/news/2024/index.rst index 182f84ad..046b6c6a 100644 --- a/source/news/2024/index.rst +++ b/source/news/2024/index.rst @@ -10,7 +10,7 @@ News archive for the year 2024. :email: unit-owner@nginx.org :title: Unit 1.33.0 Released :url: news/2024/unit-1.33.0-released - :date: 2024-09-17 + :date: 2024-09-18 .. nxt_news_entry:: :author: Unit Team diff --git a/source/news/2024/unit-1.33.0-released.rst b/source/news/2024/unit-1.33.0-released.rst index 2f3bf5a1..1f891e5c 100644 --- a/source/news/2024/unit-1.33.0-released.rst +++ b/source/news/2024/unit-1.33.0-released.rst @@ -168,7 +168,7 @@ Full Changelog .. code-block:: none - Changes with Unit 1.33.0 17 Sep 2024 + Changes with Unit 1.33.0 18 Sep 2024 *) Feature: show list of loaded language modules in the /status endpoint.