Skip to content

Commit e51762c

Browse files
JTorreGmjangADubhlaoich
authored
docs: Transfer Unit docs (#171)
* docs: migrate UNIT to hugo and documentation repo * docs: fixes * docs: update news and fix links * fix: fix broken code block * fix: fix some code blocks * docs: remove unused include * add-pull-173 --------- Co-authored-by: Mike Jang <3287976+mjang@users.noreply.github.com> Co-authored-by: Alan Dooley <a.dooley@f5.com>
1 parent 507005d commit e51762c

File tree

152 files changed

+24396
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

152 files changed

+24396
-1
lines changed

‎config/_default/config.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,8 @@ enableGitInfo = true
4747
"taxonomyTerm"
4848
]
4949
taxonomiesExcludedFromSitemap = ["tags", "categories", "doctypes"]
50-
50+
unitversion= "1.34.1"
51+
unitversionv= "v1.34.1"
5152
#logo = ""
5253

5354
# Version lists; used by the versions shortcode

‎content/includes/unit/howto_change_ownership.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Run the following command (as root) so Unit can access the application
2+
directory (If the application uses several directories, run the command for
3+
each one):
4+
5+
```console
6+
# chown -R unit:unit /path/to/app/ # User and group that Unit's router runs as by default
7+
```
8+
9+
10+
{{< note >}}
11+
The **unit:unit** user-group pair is available only with
12+
[official packages]({{< relref "/unit/installation.md#installation-precomp-pkgs" >}})
13+
, Docker [images]({{< relref "/unit/installation.md#installation-docker" >}}),
14+
and some [third-party repos]({{< relref "/unit/installation.md#installation-community-repos" >}}). Otherwise, account names may differ; run the `ps aux | grep unitd` command to be sure.
15+
{{< /note >}}
16+
17+
For further details, including permissions, see the
18+
[security checklist]({{< relref "/unit/howto/security.md#secutiry-apps" >}}).

‎content/includes/unit/howto_install_app.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Install {{ app }}'s [app-link]. Here, we install it at **/path/to/app/**; use
2+
a real path in your configuration.

‎content/includes/unit/howto_install_prereq.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Install and configure {{ app }}'s [app-preq].

‎content/includes/unit/howto_install_unit.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Install [Unit]({{< relref "/unit/installation.md#installation-precomp-pkgs" >}}) with a {{ mod }} language module.

‎content/includes/unit/howto_upload_config.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Assuming the JSON above was added to
2+
`config.json`. Run the following command as root:
3+
4+
```console
5+
# curl -X PUT --data-binary @config.json --unix-socket \
6+
/path/to/control.unit.sock \ # Path to Unit's control socket in your installation
7+
http://localhost/config/ # Path to the config section in Unit's control API
8+
```
9+
10+
{{< note >}}
11+
The [control socket]({{< relref "/unit/installation.md#configuration-socket" >}}) path may vary; run
12+
`unitd -h` or see
13+
[Startup and shutdown]({{< relref "/unit/howto/source.md#source-startup" >}}) for details.
14+
{{< /note >}}

‎content/includes/unit/version.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
1.34.1

‎content/unit/_index.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: NGINX Unit
3+
description: A lightweight web app server that combines several layers of the typical application stack into a single component.
4+
url: /nginx-unit/
5+
cascade:
6+
logo: "NGINX-Unit-product-icon-RGB.png"
7+
---

‎content/unit/about.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: About NGINX Unit
3+
weight: 100
4+
toc: true
5+
---
6+
7+
# Universal web app server
8+
9+
NGINX Unit is a lightweight and versatile application runtime that provides the
10+
essential components for your web application as a single open-source server:
11+
running application code (including WebAssembly), serving static assets,
12+
handling TLS and request routing.
13+
14+
Unit was created by [nginx](https://nginx.org/en/) team members from scratch to
15+
be highly efficient and fully configurable at runtime. You can read the details
16+
about the latest release in the [news]({{< relref "/unit/news/">}}) section.
17+
18+
- See a quickstart [guide](https://github.com/nginx/unit/) on our GitHub page.
19+
- Browse the [Changelog]({{< relref "/unit/changes/">}}) or see the release notes in the [Releases and announcements]({{< relref "/unit/news/">}}) archive.
20+
- Check out the discussion of our [key features]({{< relref "/unit/keyfeatures.md">}}) for further
21+
details.
22+
- Peek at our future plans with a GitHub-based [roadmap](https://github.com/orgs/nginx/projects/1).
23+
24+
25+
Watch the entire NGINX Unit tutorial course in the [NGINX YouTube channel](https://www.youtube.com/playlist?list=PLGz_X9w9raXdV3vuPUu0kKBSBjG9rPaUf).

‎content/unit/certificates.md

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: SSL/TLS certificates
3+
weight: 800
4+
toc: true
5+
---
6+
7+
The **/certificates** section of the [control API]({{< relref "/unit/controlapi.md" >}})
8+
handles TLS certificates that are used with Unit's
9+
[listeners]({{< relref "/unit/configuration.md#configuration-listeners">}}).
10+
To set up SSL/TLS for a listener, upload a **.pem** file with your certificate
11+
chain and private key to Unit, and name the uploaded bundle in the listener's configuration; next, the listener can be accessed via SSL/TLS.
12+
13+
{{< note >}}
14+
For the details of certificate issuance and renewal in Unit,
15+
see an example in [TLS with Certbot]({{< relref "/unit/howto/certbot.md" >}}).
16+
{{< /note >}}
17+
18+
19+
First, create a **.pem** file with your certificate chain and private key:
20+
21+
```console
22+
cat cert.pem ca.pem key.pem > bundle.pem # Leaf certificate file | CA certificate file | Private key file | Arbitrary certificate bundle's filename
23+
```
24+
25+
Usually, your website's certificate (optionally followed by the intermediate CA certificate) is enough to build a certificate chain. If you add more certificates
26+
to your chain, order them leaf to root.
27+
28+
Upload the resulting bundle file to Unit's certificate storage under a suitable name
29+
(in this case, **bundle**), running the following command as root:
30+
31+
```console
32+
# curl -X PUT --data-binary @bundle.pem --unix-socket /path/to/control.unit.sock http://localhost/certificates/bundle
33+
34+
{
35+
"success": "Certificate chain uploaded."
36+
}
37+
```
38+
39+
{{< warning >}}
40+
Don't use **-d** for file upload with `curl`; this option damages **.pem** files.
41+
Use the **--data-binary** option when uploading file-based data to avoid data
42+
corruption.
43+
{{< /warning >}}
44+
45+
Internally, Unit stores the uploaded certificate bundles along with other configuration data in its **state** subdirectory; the
46+
[control API]({{< relref "/unit/controlapi.md" >}})
47+
exposes some of their properties as **GET**-table JSON using **/certificates**:
48+
49+
```json
50+
{
51+
"certificates": {
52+
"bundle": {
53+
"key": "RSA (4096 bits)",
54+
"chain": [
55+
{
56+
"subject": {
57+
"common_name": "example.com",
58+
"alt_names": [
59+
"example.com",
60+
"www.example.com"
61+
],
62+
63+
"country": "US",
64+
"state_or_province": "CA",
65+
"organization": "Acme, Inc."
66+
},
67+
68+
"issuer": {
69+
"common_name": "intermediate.ca.example.com",
70+
"country": "US",
71+
"state_or_province": "CA",
72+
"organization": "Acme Certification Authority"
73+
},
74+
75+
"validity": {
76+
"since": "Sep 18 19:46:19 2022 GMT",
77+
"until": "Jun 15 19:46:19 2025 GMT"
78+
}
79+
},
80+
{
81+
"subject": {
82+
"common_name": "intermediate.ca.example.com",
83+
"country": "US",
84+
"state_or_province": "CA",
85+
"organization": "Acme Certification Authority"
86+
},
87+
88+
"issuer": {
89+
"common_name": "root.ca.example.com",
90+
"country": "US",
91+
"state_or_province": "CA",
92+
"organization": "Acme Root Certification Authority"
93+
},
94+
95+
"validity": {
96+
"since": "Feb 22 22:45:55 2023 GMT",
97+
"until": "Feb 21 22:45:55 2026 GMT"
98+
}
99+
}
100+
]
101+
}
102+
}
103+
}
104+
```
105+
106+
{{< note >}}
107+
Access array items, such as individual certificates in a chain,
108+
and their properties by indexing, running the following commands as root:
109+
110+
```console
111+
# curl -X GET --unix-socket /path/to/control.unit.sock \ # Path to Unit's control socket in your installation
112+
http://localhost/certificates/bundle/chain/0/ # Certificate bundle name
113+
```
114+
115+
```console
116+
# curl -X GET --unix-socket /path/to/control.unit.sock \ # Path to Unit's control socket in your installation
117+
http://localhost/certificates/bundle/chain/0/subject/alt_names/0/ # Certificate bundle name
118+
```
119+
{{< /note >}}
120+
121+
Next, add the uploaded bundle to a
122+
[listener]({{< relref "/unit/configuration.md#configuration-listeners" >}}).
123+
the resulting control API configuration may look like this:
124+
125+
```json
126+
{
127+
"certificates": {
128+
"bundle": {
129+
"key": "<key type>",
130+
"chain": [
131+
"<certificate chain, omitted for brevity>"
132+
],
133+
"comment_bundle": "Certificate bundle name"
134+
}
135+
},
136+
137+
"config": {
138+
"listeners": {
139+
"*:443": {
140+
"pass": "applications/wsgi-app",
141+
"tls": {
142+
"certificate": "bundle",
143+
"comment_certificate": "Certificate bundle name"
144+
}
145+
}
146+
},
147+
148+
"applications": {
149+
"wsgi-app": {
150+
"type": "python",
151+
"module": "wsgi",
152+
"path": "/usr/www/wsgi-app/"
153+
}
154+
}
155+
}
156+
}
157+
```
158+
159+
All done;
160+
the application is now accessible via SSL/TLS:
161+
162+
```console
163+
$ curl -v https://127.0.0.1 # Port 443 is conventionally used for HTTPS connections
164+
...
165+
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
166+
* TLSv1.2 (IN), TLS handshake, Server hello (2):
167+
* TLSv1.2 (IN), TLS handshake, Certificate (11):
168+
* TLSv1.2 (IN), TLS handshake, Server finished (14):
169+
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
170+
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
171+
* TLSv1.2 (OUT), TLS handshake, Finished (20):
172+
* TLSv1.2 (IN), TLS change cipher, Client hello (1):
173+
* TLSv1.2 (IN), TLS handshake, Finished (20):
174+
* SSL connection using TLSv1.2 / AES256-GCM-SHA384
175+
...
176+
```
177+
178+
Finally, you can delete a certificate bundle that you don't need anymore
179+
from the storage, running the following command as root:
180+
181+
```console
182+
# curl -X DELETE --unix-socket /path/to/control.unit.sock \ # Path to Unit's control socket in your installation
183+
http://localhost/certificates/bundle # Certificate bundle name
184+
185+
{
186+
"success": "Certificate deleted."
187+
}
188+
```
189+
190+
{{< note >}}
191+
You can't delete certificate bundles still referenced in your configuration,
192+
overwrite existing bundles using **put**, or delete non-existent ones.
193+
{{< /note >}}

0 commit comments

Comments
 (0)