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/conf.py b/source/conf.py index 8c35115f..829b3a29 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 = 'Sep 18, 2024' release = version needs_sphinx = '6.2' diff --git a/source/configuration.rst b/source/configuration/index.rst similarity index 97% rename from source/configuration.rst rename to source/configuration/index.rst index 1e71a462..a8c6ff95 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 @@ -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 @@ -402,6 +421,8 @@ The **tickets** option works as follows: LoYjFVxpUFFOj4TzGkr5MsSIRMjhuh8RCsVvtIJiQ12FGhn0nhvvQsEND1+OugQ7 + .. code-block:: console + $ openssl rand -base64 80 GQczhdXawyhTrWrtOXI7l3YYUY98PrFYzjGhBbiQsAWgaxm+mbkm4MmZZpDw0tkK @@ -1952,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 @@ -2028,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 @@ -2228,7 +2258,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 +2471,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: @@ -2758,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 @@ -2775,6 +2810,8 @@ won't be resolved. index.html + .. code-block:: console + $ curl http://localhost/symlink index.html @@ -2800,6 +2837,8 @@ won't be resolved. index.html + .. code-block:: console + $ curl http://localhost/symlink Error 403

Error 403. @@ -3293,14 +3332,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 when running *with* **--no-daemon** is to send + *stdout* to the *console* and *stderr* to Unit's *log*. - The default is **/dev/null**. + The default when running *without* **--no-daemon** is to send + *stdout* to */dev/null* and *stderr* to Unit's *log*. - When running in **--no-daemon** mode, application output - is always redirected to - :ref:`Unit's log file `. + These options have *no* effect when running with **--no-daemon**. * - **user** - String; @@ -3646,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 @@ -3966,6 +4008,8 @@ and rebuild the app. 0 + .. code-block:: console + $ go env -w CGO_ENABLED=1 - If you installed Unit from the @@ -3988,7 +4032,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 +4145,7 @@ Example: For Go-based examples, see our - :doc:`howto/grafana` + :doc:`../howto/grafana` howto or a basic :ref:`sample `. @@ -4191,10 +4235,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 +4387,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 +4456,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 +4709,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 `. @@ -4720,6 +4764,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 @@ -4972,27 +5026,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 +5164,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 `. @@ -5357,6 +5411,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 @@ -5366,9 +5430,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: @@ -5469,6 +5533,8 @@ In turn, the **http** option exposes the following settings: The default is **true**. + *(since 1.30.0)* + * - **static** - Object; configures static asset handling. @@ -5591,7 +5657,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 e6b8dbea..2b4c0f35 100644 --- a/source/contents.rst +++ b/source/contents.rst @@ -6,10 +6,11 @@ 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..c0461147 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 @@ -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 1351ef76..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,9 +402,12 @@ 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>` Unit as follows: + #. To run a single app, :doc:`configure <../configuration/index>` Unit as follows: .. code-block:: json @@ -397,7 +438,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: @@ -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/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/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/news/2024/index.rst b/source/news/2024/index.rst index 7019e68f..046b6c6a 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 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 + :date: 2024-09-18 + .. 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..1f891e5c --- /dev/null +++ b/source/news/2024/unit-1.33.0-released.rst @@ -0,0 +1,224 @@ +:orphan: + +#################### +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: + +************************* +New configuration options +************************* + +This release introduces three new configuration options: + +#. **listen_threads** + + 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. + +#. **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. + + The default value is 'false'. + + NOTE: Unit does **not** support passing arguments to factories. + +**************** +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 +**************************** + +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**. + +************************************* +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. + + 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 several lesser-known compilers. GCC and Clang are now the +only supported compilers for building Unit. + +========== +-std=gnu11 +========== + +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**. + + +************ +Wall of fame +************ + +Special Thanks to all external contributors helping us +making Unit better! With 1.33.0 we would like to send a shout out to: + +- Alejandro Colomar +- Costas Drongos +- Gourav +- Remi Collet +- Robbie McKinstry + +Special thanks to Arjun for his fuzzing work. + +************** +Full Changelog +************** + +.. code-block:: none + + Changes with Unit 1.33.0 18 Sep 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". + + *) 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. + + *) 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: fix a crash when interrupting a download via a proxy. + + *) 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. 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 ` 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'); } 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 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 new file mode 100644 index 00000000..a654ef19 --- /dev/null +++ b/source/unitctl.rst @@ -0,0 +1,405 @@ + .. meta:: + :og:description: Learn how to use the Unit CLI. + +.. include:: include/replace.rst +.. _unitctl: + +############# +CLI (unitctl) +############# + +.. note:: + + **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 +interface (unitctl) that exposes the functionality provided by the SDK. + +This CLI is a multi-purpose tool that allows you to deploy, manage, and configure +Unit in your environment. + +***************** +Download binaries +***************** + +Unitctl binaries are available for Linux (ARM64 and X64) and macOS systems. + +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 +`_. + +************* +Using unitctl +************* + +The unitctl CLI offers several commands to interact with Unit. Here are the available commands: + +.. list-table:: + :header-rows: 1 + + * - Command + - Description + + * - **instances** + - List all running Unit processes + + * - **apps** + - List and restart active applications + + * - **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 + + * - **execute** + - Send a raw JSON payload to Unit + + * - **status** + - Get the current status of 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 ++++++++++++++++++++++++++++++++++ + +The **instances** command lets you list all running Unit processes and +deploy new instances of Unit. + +The **instances** command has the following option: + +.. list-table:: + :header-rows: 1 + + * - Option + - Description + + * - **new** + - Deploy a new instance of Unit + +Running unitcl with the **instances** command shows output similar to this: + +.. 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 + +You can use the **new** option with three arguments to deploy a new instance of Unit: + +1. **Control API path**: A file path for a Unix socket or a TCP address with port. + + - If you specify a directory, the Unit container will mount it to **/var/run** internally. + The control socket and pid file are accessible from the host. Example: **/tmp/2**. + - If you specify a TCP address, the Unit container will listen on this + address and port. Example: **127.0.0.1:7171**. + +2. **Application path**. The Unit container will mount this path in read-only mode + to **/www** internally. This setup allows you to configure the Unit + container to expose an application stored on the host. Example: **$(pwd)**. + +3. **Image tag**: Unitctl will deploy this image, enabling you use custom + images. For example: **unit:wasm**. + +.. 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 running apps ++++++++++++++++++++++++++++++ + +The **apps** command lets you list and restart active applications. + +Options +------- + +The **apps** command has the following options: + +.. list-table:: + :header-rows: 1 + + * - Option + - Description + + * - **list** + - List all active applications + + * - **restart ** + - Restart the specified application + +To list active applications, run: + +.. code-block:: console + + $ unitctl apps list + { + "wasm": { + "type": "wasm-wasi-component", + "component": "/www/wasmapp-proxy-component.wasm" + } + } + +To restart an application, run: + +.. code-block:: console + + $ unitctl apps restart 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: + +.. 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: + +.. 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 ++++++++++++++++++++++++++++++++++++ + +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 + + $ 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 a preconfigured editor on your command line using the **edit** command. + +Unitctl tries to use the editor configured with the **EDITOR** environment +variable, but defaults to vim, emacs, nano, vi, or pico if **EDITOR** is not set. + +To edit the current configuration, run: + +.. code-block:: console + + $ unitctl edit + +The configuration loads into the editor, allowing you to make any necessary +changes. Once you save and close the editor, you see the following output: + +.. 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 ++++++++++++++++++++++++++++++++++++++++++ + +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: + +.. 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 ++++++++++++++++++++++++++++++++++++++ + +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 + + $ 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:: + + 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 for Unix sockets to become available: + +.. 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