git.squeep.com Git - akkoma/blob - docs/installation/openbsd_en.md

   1 # Installing on OpenBSD
   2
   3 This guide describes the installation and configuration of pleroma (and the required software to run it) on a single OpenBSD 6.4 server.
   4
   5 For any additional information regarding commands and configuration files mentioned here, check the man pages [online](https://man.openbsd.org/) or directly on your server with the man command.
   6
   7 #### Required software
   8
   9 The following packages need to be installed:
  10
  11   * elixir
  12   * gmake
  13   * ImageMagick
  14   * git
  15   * postgresql-server
  16   * postgresql-contrib
  17
  18 To install them, run the following command (with doas or as root):
  19
  20 ```
  21 pkg_add elixir gmake ImageMagick git postgresql-server postgresql-contrib
  22 ```
  23
  24 Pleroma requires a reverse proxy, OpenBSD has relayd in base (and is used in this guide) and packages/ports are available for nginx (www/nginx) and apache (www/apache-httpd). Independently of the reverse proxy, [acme-client(1)](https://man.openbsd.org/acme-client) can be used to get a certificate from Let's Encrypt.
  25
  26 #### Creating the pleroma user
  27 Pleroma will be run by a dedicated user, \_pleroma. Before creating it, insert the following lines in login.conf:
  28 ```
  29 pleroma:\
  30         :datasize-max=1536M:\
  31         :datasize-cur=1536M:\
  32         :openfiles-max=4096
  33 ```
  34 This creates a "pleroma" login class and sets higher values than default for datasize and openfiles (see [login.conf(5)](https://man.openbsd.org/login.conf)), this is required to avoid having pleroma crash some time after starting.
  35
  36 Create the \_pleroma user, assign it the pleroma login class and create its home directory (/home/\_pleroma/): `useradd -m -L pleroma _pleroma`
  37
  38 #### Clone pleroma's directory
  39 Enter a shell as the \_pleroma user. As root, run `su _pleroma -;cd`. Then clone the repository with `git clone -b stable https://git.pleroma.social/pleroma/pleroma.git`. Pleroma is now installed in /home/\_pleroma/pleroma/, it will be configured and started at the end of this guide.
  40
  41 #### PostgreSQL
  42 Start a shell as the \_postgresql user (as root run `su _postgresql -` then run the `initdb` command to initialize postgresql:
  43 If you wish to not use the default location for postgresql's data (/var/postgresql/data), add the following switch at the end of the command: `-D <path>` and modify the `datadir` variable in the /etc/rc.d/postgresql script.
  44
  45 When this is done, enable postgresql so that it starts on boot and start it. As root, run:
  46 ```
  47 rcctl enable postgresql
  48 rcctl start postgresql
  49 ```
  50 To check that it started properly and didn't fail right after starting, you can run `ps aux | grep postgres`, there should be multiple lines of output.
  51
  52 #### httpd
  53 httpd will have three fuctions:
  54
  55   * redirect requests trying to reach the instance over http to the https URL
  56   * serve a robots.txt file
  57   * get Let's Encrypt certificates, with acme-client
  58
  59 Insert the following config in httpd.conf:
  60 ```
  61 # $OpenBSD: httpd.conf,v 1.17 2017/04/16 08:50:49 ajacoutot Exp $
  62
  63 ext_inet="<IPv4 address>"
  64 ext_inet6="<IPv6 address>"
  65
  66 server "default" {
  67         listen on $ext_inet port 80 # Comment to disable listening on IPv4
  68         listen on $ext_inet6 port 80 # Comment to disable listening on IPv6
  69         listen on 127.0.0.1 port 80 # Do NOT comment this line
  70
  71         log syslog
  72         directory no index
  73
  74         location "/.well-known/acme-challenge/*" {
  75                 root "/acme"
  76                 request strip 2
  77         }
  78
  79         location "/robots.txt" { root "/htdocs/local/" }
  80         location "/*" { block return 302 "https://$HTTP_HOST$REQUEST_URI" }
  81 }
  82
  83 types {
  84         include "/usr/share/misc/mime.types"
  85 }
  86 ```
  87 Do not forget to change *<IPv4/6 address\>* to your server's address(es). If httpd should only listen on one protocol family, comment one of the two first *listen* options.
  88
  89 Create the /var/www/htdocs/local/ folder and write the content of your robots.txt in /var/www/htdocs/local/robots.txt.
  90 Check the configuration with `httpd -n`, if it is OK enable and start httpd (as root):
  91 ```
  92 rcctl enable httpd
  93 rcctl start httpd
  94 ```
  95
  96 #### acme-client
  97 acme-client is used to get SSL/TLS certificates from Let's Encrypt.
  98 Insert the following configuration in /etc/acme-client.conf:
  99 ```
 100 #
 101 # $OpenBSD: acme-client.conf,v 1.4 2017/03/22 11:14:14 benno Exp $
 102 #
 103
 104 authority letsencrypt-<domain name> {
 105         #agreement url "https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf"
 106         api url "https://acme-v01.api.letsencrypt.org/directory"
 107         account key "/etc/acme/letsencrypt-privkey-<domain name>.pem"
 108 }
 109
 110 domain <domain name> {
 111         domain key "/etc/ssl/private/<domain name>.key"
 112         domain certificate "/etc/ssl/<domain name>.crt"
 113         domain full chain certificate "/etc/ssl/<domain name>.fullchain.pem"
 114         sign with letsencrypt-<domain name>
 115         challengedir "/var/www/acme/"
 116 }
 117 ```
 118 Replace *<domain name\>* by the domain name you'll use for your instance. As root, run `acme-client -n` to check the config, then `acme-client -ADv <domain name>` to create account and domain keys, and request a certificate for the first time.
 119 Make acme-client run everyday by adding it in /etc/daily.local. As root, run the following command: `echo "acme-client <domain name>" >> /etc/daily.local`.
 120
 121 Relayd will look for certificates and keys based on the address it listens on (see next part), the easiest way to make them available to relayd is to create a link, as root run:
 122 ```
 123 ln -s /etc/ssl/<domain name>.fullchain.pem /etc/ssl/<IP address>.crt
 124 ln -s /etc/ssl/private/<domain name>.key /etc/ssl/private/<IP address>.key
 125 ```
 126 This will have to be done for each IPv4 and IPv6 address relayd listens on.
 127
 128 #### relayd
 129 relayd will be used as the reverse proxy sitting in front of pleroma.
 130 Insert the following configuration in /etc/relayd.conf:
 131 ```
 132 # $OpenBSD: relayd.conf,v 1.4 2018/03/23 09:55:06 claudio Exp $
 133
 134 ext_inet="<IPv4 address>"
 135 ext_inet6="<IPv6 address>"
 136
 137 table <pleroma_server> { 127.0.0.1 }
 138 table <httpd_server> { 127.0.0.1 }
 139
 140 http protocol plerup { # Protocol for upstream pleroma server
 141         #tcp { nodelay, sack, socket buffer 65536, backlog 128 } # Uncomment and adjust as you see fit
 142         tls ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
 143         tls ecdhe secp384r1
 144
 145         # Forward some paths to the local server (as pleroma won't respond to them as you might want)
 146         pass request quick path "/robots.txt" forward to <httpd_server>
 147
 148         # Append a bunch of headers
 149         match request header append "X-Forwarded-For" value "$REMOTE_ADDR" # This two header and the next one are not strictly required by pleroma but adding them won't hurt
 150         match request header append "X-Forwarded-By" value "$SERVER_ADDR:$SERVER_PORT"
 151
 152         match response header append "X-XSS-Protection" value "1; mode=block"
 153         match response header append "X-Permitted-Cross-Domain-Policies" value "none"
 154         match response header append "X-Frame-Options" value "DENY"
 155         match response header append "X-Content-Type-Options" value "nosniff"
 156         match response header append "Referrer-Policy" value "same-origin"
 157         match response header append "X-Download-Options" value "noopen"
 158         match response header append "Content-Security-Policy" value "default-src 'none'; base-uri 'self'; form-action 'self'; img-src 'self' data: https:; media-src 'self' https:; style-src 'self' 'unsafe-inline'; font-src 'self'; script-src 'self'; connect-src 'self' wss://CHANGEME.tld; upgrade-insecure-requests;" # Modify "CHANGEME.tld" and set your instance's domain here
 159         match request header append "Connection" value "upgrade"
 160         #match response header append "Strict-Transport-Security" value "max-age=31536000; includeSubDomains" # Uncomment this only after you get HTTPS working.
 161
 162         # If you do not want remote frontends to be able to access your Pleroma backend server, comment these lines
 163         match response header append "Access-Control-Allow-Origin" value "*"
 164         match response header append "Access-Control-Allow-Methods" value "POST, PUT, DELETE, GET, PATCH, OPTIONS"
 165         match response header append "Access-Control-Allow-Headers" value "Authorization, Content-Type, Idempotency-Key"
 166         match response header append "Access-Control-Expose-Headers" value "Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id"
 167         # Stop commenting lines here
 168 }
 169
 170 relay wwwtls {
 171         listen on $ext_inet port https tls # Comment to disable listening on IPv4
 172         listen on $ext_inet6 port https tls # Comment to disable listening on IPv6
 173
 174         protocol plerup
 175
 176         forward to <pleroma_server> port 4000 check http "/" code 200
 177         forward to <httpd_server> port 80 check http "/robots.txt" code 200
 178 }
 179 ```
 180 Again, change *<IPv4/6 address\>* to your server's address(es) and comment one of the two *listen* options if needed. Also change *wss://CHANGEME.tld* to *wss://<your instance's domain name\>*.
 181 Check the configuration with `relayd -n`, if it is OK enable and start relayd (as root):
 182 ```
 183 rcctl enable relayd
 184 rcctl start relayd
 185 ```
 186
 187 #### pf
 188 Enabling and configuring pf is highly recommended.
 189 In /etc/pf.conf, insert the following configuration:
 190 ```
 191 # Macros
 192 if="<network interface>"
 193 authorized_ssh_clients="any"
 194
 195 # Skip traffic on loopback interface
 196 set skip on lo
 197
 198 # Default behavior
 199 set block-policy drop
 200 block in log all
 201 pass out quick
 202
 203 # Security features
 204 match in all scrub (no-df random-id)
 205 block in log from urpf-failed
 206
 207 # Rules
 208 pass in quick on $if inet proto icmp to ($if) icmp-type { echoreq unreach paramprob trace } # ICMP
 209 pass in quick on $if inet6 proto icmp6 to ($if) icmp6-type { echoreq unreach paramprob timex toobig } # ICMPv6
 210 pass in quick on $if proto tcp to ($if) port { http https } # relayd/httpd
 211 pass in quick on $if proto tcp from $authorized_ssh_clients to ($if) port ssh
 212 ```
 213 Replace *<network interface\>* by your server's network interface name (which you can get with ifconfig). Consider replacing the content of the authorized\_ssh\_clients macro by, for exemple, your home IP address, to avoid SSH connection attempts from bots.
 214
 215 Check pf's configuration by running `pfctl -nf /etc/pf.conf`, load it with `pfctl -f /etc/pf.conf` and enable pf at boot with `rcctl enable pf`.
 216
 217 #### Configure and start pleroma
 218 Enter a shell as \_pleroma (as root `su _pleroma -`) and enter pleroma's installation directory (`cd ~/pleroma/`).
 219
 220 Then follow the main installation guide:
 221
 222   * run `mix deps.get`
 223   * run `mix pleroma.instance gen` and enter your instance's information when asked
 224   * copy config/generated\_config.exs to config/prod.secret.exs. The default values should be sufficient but you should edit it and check that everything seems OK.
 225   * exit your current shell back to a root one and run `psql -U postgres -f /home/_pleroma/config/setup_db.psql` to setup the database.
 226   * return to a \_pleroma shell into pleroma's installation directory (`su _pleroma -;cd ~/pleroma`) and run `MIX_ENV=prod mix ecto.migrate`
 227
 228 As \_pleroma in /home/\_pleroma/pleroma, you can now run `LC_ALL=en_US.UTF-8 MIX_ENV=prod mix phx.server` to start your instance.
 229 In another SSH session/tmux window, check that it is working properly by running `ftp -MVo - http://127.0.0.1:4000/api/v1/instance`, you should get json output. Double-check that *uri*'s value is your instance's domain name.
 230
 231 ##### Starting pleroma at boot
 232 An rc script to automatically start pleroma at boot hasn't been written yet, it can be run in a tmux session (tmux is in base).