====== Caddy ======

[[https://caddyserver.com/|Caddy]] is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go.

  * [[https://www.freshports.org/www/caddy/|www/caddy]]
  * [[https://www.freshports.org/www/caddy-custom/|www/caddy-custom]]

===== Running as Non-Root =====

Most webservers support running as non-root users by way of //starting// as root,
binding their privileged ports (80 and 443), and then changing to their configured
user themselves.

Caddy doesn't support this, instead favouring operating system support for allowing
specific processes or users to bind to privileged ports.  This requires some
configuration - which is why the port currently defaults to running it as root.

First we'll install and configure Caddy:

<code bash>
pkg install www/caddy
sysrc caddy_user=www caddy_group=www
</code>

Now we'll use [[https://www.freshports.org/security/portacl-rc/|security/portacl-rc]]
to configure [[https://man.freebsd.org/cgi/man.cgi?query=mac_portacl&sektion=4|mac_portacl(4)]],
which will enable the ''%%www%%'' user to bind to webserver ports:

<code bash>
pkg install security/portacl-rc
sysrc portacl_users+=www
sysrc portacl_user_www_tcp="http https"
sysrc portacl_user_www_udp="https"
service enable portacl
service start portacl
</code>

If you've previously launched Caddy as the stock root:wheel user it will have
created files and directories which will need their ownership adjusting:

<code bash>
service caddy stop
chown -r www:www /var/db/caddy /var/log/caddy /var/run/caddy
</code>

You should now be able to ''%%service start caddy%%'' and have a basic webserver configured
on ''%%localhost%%''.

<callout type="info">
''%%caddy_logfile%%'' (default ''%%/var/log/caddy/caddy.log%%'') is a redirection of ''%%caddy%%''
console output, which will be opened by the ''%%rc(8)%%'' script as root:wheel.

You should avoid overwriting this with logs from Caddy itself.

There is currently no mechanism to rotate this file, though it should remain small.
</callout>

===== Running Caddy in a Jail =====

Follow the same instructions as above, installing ''%%security/portacl-rc%%'' on the
host and ''%%www/caddy%%'' in the jail.

You will likely also want to create the ''%%www%%'' user and group on the host, which
can be done either by temporarily installing ''%%www/caddy%%'' there, or by manually
creating the accounts:

<code bash>
pw groupadd www -g 80
pw useradd www -u 80 -g 80 -c "World Wide Web Owner" -d /nonexistent -s /usr/sbin/nologin
</code>

Further configuration will normally be required to expose a jailed webserver to the
outside world - this is outside the scope of this document.

==== VNET Jails ====

If you're installing Caddy to a [[/Jails#VNET-based_networking_for_Jails|VNET]] jail
you must also disable the jail's local reserved port configuration so the host
''%%mac_portacl(4)%%'' configuration applies to it:

<code bash>
echo "net.inet.ip.portrange.reservedhigh=0" >>/path/to/jail/root/etc/sysctl.conf
</code>

Note this must be set before elevating the jail's ''%%kern.securelevel%%''.  To do this,
instead of setting ''%%securelevel = 2%%'' in ''%%jail.conf%%'' (or however your jail manager
handles it), set it in the jail's ''%%rc.conf%%'', which will elevate it after
''%%/etc/sysctl.conf%%'' has been processed:

<code bash>
sysrc -R /path/to/jail/root kern_securelevel_enable=YES kern_securelevel=2
</code>

===== The Admin Endpoint =====

Caddy exposes an admin API endpoint used for controlling the server.  By default
this has traditionally been bound to ''%%http://127.0.0.1:2019%%'', but this comes with
obvious and not-so-obvious security implications, with local users able to
reconfigure the server as they see fit, and creating a risk of request smuggling
if clients or proxies can be convinced to forward requests to it.

As of 2.7.5 the %%FreeBSD%% port changes this to a Unix domain socket in
''%%/var/run/caddy/caddy.sock%%'', where it is protected by filesystem permissions.

This should be completely transparent if you use the ''%%rc(8)%%'' script for stopping
or reloading the server, but if you are using the ''%%caddy%%'' command directly you
may wish to set the admin endpoint in your ''%%Caddyfile%%'' explicitly in its global
configuration section:

<code nginx>
admin unix//var/run/caddy/caddy.sock
</code>

This will be honoured both by the ''%%caddy%%'' command when the Caddyfile is
specified, and by the rc(8) service script.

===== Further Configuration =====

Now you have a basic Caddy setup, please refer to the
[[https://caddyserver.com/docs/|official documentation]] for the rest of your
configuration.

A simple [[https://caddyserver.com/docs/caddyfile|Caddyfile]] is installed to
''%%/usr/local/etc/caddy/Caddyfile%%'' to help get you started.