1UALPN(1) User Commands UALPN(1)
2
6 ualpn - lightweight proxying ACMEv2 tls-alpn-01 responder
7
9 ualpn [-4|--ipv4] [-6|--ipv6] [-b|--bind address[@port]] [-c|--connect
10 address[@port]] [-d|--daemon] [-l|--logfile file] [-m|--max-auths N]
11 [-n|--num-workers N] [-p|--pidfile file] [-P|--proxy N] [-r|--chroot
12 dir] [-s|--sock path] [-S|--sock-mode mode] [-t|--terminate] [-u|--user
13 user[:group]] [-v|--verbose ...] [-V|--version] [-?|--help]
14
16 ualpn is a lightweight proxying ACMEv2 tls-alpn-01 challenge responder
17 compliant with RFC8737 (https://tools.ietf.org/html/RFC8737) and
18 RFC8738 (https://tools.ietf.org/html/RFC8738).
19 Depending on how it is invoked, ualpn runs in either client or server
21 mode. In client mode ualpn connects to a running server mode instance
22 of itself through a unix domain socket, in order to add or remove
23 ACMEv2 authorizations. See CLIENT MODE below.
24 In server mode ualpn listens for incoming connections (by default on
26 port 443, which is mandatory for tls-alpn-01 challenges). It then
27 handles any such connection in one of two different ways:
28 • if the connection begins with a "ClientHello" TLS handshake packet
30 including a "acme-tls/1" RFC7301 Application Level Protocol
31 Negotiation extension and a RFC6066 Server Name Indication
32 extension matching an identifier for which it has an authorization,
33 ualpn performs the tls-alpn-01 handshake and closes the connection;
34 • otherwise ualpn transparently proxies the connection to one of the
36 backend servers it is configured with. By default ualpn adds PROXY
37 v1 headers
38 (http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) in
39 order to safely transport connection information such as the
40 client’s address to the backend. The PROXY protocol is currently
41 supported by apache, nginx and several other server programs.
42 The event-driven implementation is based on libev
44 (http://libev.schmorp.de) and considerably reduces the cost of context
45 switches and memory usage. In addition on systems such as Linux
46 supporting the splice() system call, ualpn is able to move network data
47 without copying it to/from kernel/user address space.
48
50 -4, --ipv4
51 Only listen to IPv4 connections
52 -6, --ipv6
54 Only listen to IPv6 connections
55 -b, --bind address[@port]
57 Enable server mode and listen to address. The address must be
58 specified in numeric format using the standard IPv4 or IPv6
59 notation. Optionally, a port number can be given (default is 443).
60 This flag can be specified multiple times to listen to multiple IP
61 addresses. If this flag is not specified and server mode was
62 enabled by some other option, ualpn listens to the wildcard
63 interface; otherwise it runs in client mode (see CLIENT MODE
64 below).
65 -c, --connect address[@port]
67 Enable server mode and add a new backend. The backend address must
68 be specified in numeric format using the standard IPv4 or IPv6
69 notation. Optionally, a port number can be given (default is 443).
70 This flag can be specified multiple times to add multiple backends.
71 This flag must be specified at least once in server mode.
72 -d, --daemon
74 Enable server mode and fork in the background
75 -l, --logfile file
77 Log to file. By default ualpn logs to syslog if -d, --daemon was
78 specified or stderr otherwise. See also -v, --verbose
79 -m, --max-auths N
81 Enable server mode and allow managing ACMEv2 tls-alpn-01 challenges
82 for up to N different identifiers (default 100)
83 -n, --num-workers N
85 Enable server mode and spawn N worker processes (default 2) to
86 handle connections. Note that worker processes are single threaded
87 but thanks to the event based implementation each can handle
88 several (potentially thousands) connections concurrently.
89 -p, --pidfile file
91 Specify pidfile location (default /var/run/ualpn.pid)
92 -P, --proxy N
94 Enable server mode and disable (0) or specify (1, 2) the PROXY
95 header version (default 1). The backend server needs to be
96 configured accordingly:
97 • nginx:
99 https://docs.nginx.com/nginx/admin-guide/load-balancer/using-proxy-protocol
100 • apache:
102 https://httpd.apache.org/docs/2.4/mod/mod_remoteip.html#remoteipproxyprotocol
103 -r, --chroot dir
105 Enable server mode and specify a directory to chroot to. If logging
106 to syslog it is necessary to ensure that a syslogd(8) socket is
107 available at /dev/log in the chroot directory, otherwise ualpn will
108 not produce any log output.
109 -s, --sock path
111 Specify unix socket path (default /var/run/ualpn.sock)
112 -S, --sock-mode mode
114 Enable server mode and specify socket access permissions (default
115 644)
116 -t, --terminate
118 Try to terminate a running ualpn server. This is achieved by
119 looking up the process id stored by the server in the pidfile (see
120 -p, --pidfile) and signalling it to terminate.
121 -u, --user user[:group]
123 Enable server mode and drop user (and optionally group) privileges
124 to those of user after binding the sockets. Also affects the
125 ownership of the unix socket, pidfile and logfile (if any).
126 -v, --verbose
128 By default ualpn only produces logs upon errors or warnings. When
129 this option is specified ualpn also logs notice messages. This
130 option can be specified more than once to increase verbosity and
131 include information (twice) or debug (three times) messages.
132 -V, --version
134 Print program version on stderr and exit.
135 -?, --help
137 Print a brief usage text on stderr and exit.
138
140 In client mode ualpn pipes stdin/stdout to/from the unix socket of the
141 running server instance of itself. The protocol is ASCII text based,
142 case sensitive, line oriented, with two commands:
143 auth identifier authorization
145 The auth command instructs the running ualpn server to handle
146 ACMEv2 tls-alpn-01 challenges for identifier, which can be a string
147 representing either a domain (type dns according to RFC8555 section
148 9.7.8) or an IP address (type ip according to RFC8738 section 6).
149 authorization must contain the base64url encoding of the SHA-256
150 digest of the key authorization computed according to RFC8737
151 section 3 (note the uacme software executes hook scripts with the
152 correct authorization passed as the 5th argument). Upon successful
153 invocation of the auth command ualpn generates a self signed
154 certificate as required by the tls-alpn-01 challenge, and then uses
155 it to perform tls-alpn-01 handshakes for the given identifier.
156 unauth identifier
158 The unauth command instructs the running ualpn server to no longer
159 handle ACMEv2 tls-alpn-01 challenges for identifier.
160 ualpn responds to both commands with a line beginning with either "OK"
162 or "ERR", followed by a space and additional error information.
163
165 ualpn -vv -d -u nobody:nogroup -c 127.0.0.1@4443 -S 666
166 start ualpn as a daemon, binding to the default port 443 on the
167 wildcard interface. Proxy connections to port 4443 on 127.0.0.1
168 After opening the sockets, drop the user privileges and run as
169 nobody:nogroup. Allow anyone on the local host to access the unix
170 socket. Also increase the verbosity to include notice and
171 information messages.
172 echo "auth www.example.com DEi0apzMOdMT2DAro57oIvn-wEzPiYcAYDh2Cvjra3I"
174 | ualpn
175 Instruct the running ualpn server to handle ACMEv2 tls-alpn-01
176 challenges for www.example.com with the given key authorization.
177 echo "unauth www.example.com" | ualpn
179 Instruct the running ualpn server to no longer handle ACMEv2
180 tls-alpn-01 challenges for www.example.com
181
183 0
184 Success
185 1
187 Failure (syntax or usage error; configuration error; processing
188 failure; unexpected error).
189
191 The ualpn.sh hook script included in the distribution can be used to
192 automate the certificate issuance with uacme, provided ualpn is
193 listening on port 443 of the webserver for the domain being validated
194 #!/bin/sh
196 ARGS=5
197 E_BADARGS=85
198 if test $# -ne "$ARGS"
200 then
201 echo "Usage: $(basename "$0") method type ident token auth" 1>&2
202 exit $E_BADARGS
203 fi
204 METHOD=$1
206 TYPE=$2
207 IDENT=$3
208 TOKEN=$4
209 AUTH=$5
210 if [ "$TYPE" != "tls-alpn-01" ]; then
212 exit 1
213 fi
214 case "$METHOD" in
216 "begin")
217 UALPN_OUT=$(echo "auth $IDENT $AUTH" | ualpn)
218 if [ "x$UALPN_OUT" = "xOK" ]; then
219 exit 0
220 else
221 exit 1
222 fi
223 ;;
224 "done"|"failed")
225 UALPN_OUT=$(echo "unauth $IDENT" | ualpn)
226 if [ "x$UALPN_OUT" = "xOK" ]; then
227 exit 0
228 else
229 exit 1
230 fi
231 ;;
232 *)
233 echo "$0: invalid method" 1>&2
234 exit 1
235 esac
236
238 If you believe you have found a bug, please create a new issue at
239 https://github.com/ndilieto/uacme/issues with any applicable
240 information.
241
243 uacme(1)
244
246 ualpn was written by Nicola Di Lieto
247
249 Copyright © 2019-2023 Nicola Di Lieto <nicola.dilieto@gmail.com>
250 This file is part of uacme.
252 uacme is free software: you can redistribute it and/or modify it under
254 the terms of the GNU General Public License as published by the Free
255 Software Foundation, either version 3 of the License, or (at your
256 option) any later version.
257 uacme is distributed in the hope that it will be useful, but WITHOUT
259 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
260 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
261 for more details.
262 You should have received a copy of the GNU General Public License along
264 with this program. If not, see http://www.gnu.org/licenses/.
265ualpn 1.7.4 07/22/2023 UALPN(1)