total rebase
[anni] / 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.6 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 {! backend/installation/generic_dependencies.include !}
8
9 ### Preparing the system
10 #### Required software
11
12 To install them, run the following command (with doas or as root):
13
14 ```
15 pkg_add elixir gmake git postgresql-server postgresql-contrib cmake ffmpeg ImageMagick
16 ```
17
18 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.
19
20 #### Optional software
21
22 Per [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md):
23   * ImageMagick
24   * ffmpeg
25   * exiftool
26
27 To install the above:
28
29 ```
30 pkg_add ImageMagick ffmpeg p5-Image-ExifTool
31 ```
32
33 #### Creating the pleroma user
34 Pleroma will be run by a dedicated user, \_pleroma. Before creating it, insert the following lines in login.conf:
35 ```
36 pleroma:\
37         :datasize-max=1536M:\
38         :datasize-cur=1536M:\
39         :openfiles-max=4096
40 ```
41 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.
42
43 Create the \_pleroma user, assign it the pleroma login class and create its home directory (/home/\_pleroma/): `useradd -m -L pleroma _pleroma`
44
45 #### Clone pleroma's directory
46 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.
47
48 #### PostgreSQL
49 Start a shell as the \_postgresql user (as root run `su _postgresql -` then run the `initdb` command to initialize postgresql:
50 You will need to specify pgdata directory to the default (/var/postgresql/data) with the `-D <path>` and set the user to postgres with the `-U <username>` flag. This can be done as follows:
51
52 ```
53 initdb -D /var/postgresql/data -U postgres
54 ```
55 If you are not using the default directory, you will have to update the `datadir` variable in the /etc/rc.d/postgresql script.
56
57 When this is done, enable postgresql so that it starts on boot and start it. As root, run:
58 ```
59 rcctl enable postgresql
60 rcctl start postgresql
61 ```
62 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.
63
64 #### httpd
65 httpd will have three functions:
66
67   * redirect requests trying to reach the instance over http to the https URL
68   * serve a robots.txt file
69   * get Let's Encrypt certificates, with acme-client
70
71 Insert the following config in httpd.conf:
72 ```
73 # $OpenBSD: httpd.conf,v 1.17 2017/04/16 08:50:49 ajacoutot Exp $
74
75 ext_inet="<IPv4 address>"
76 ext_inet6="<IPv6 address>"
77
78 server "default" {
79         listen on $ext_inet port 80 # Comment to disable listening on IPv4
80         listen on $ext_inet6 port 80 # Comment to disable listening on IPv6
81         listen on 127.0.0.1 port 80 # Do NOT comment this line
82
83         log syslog
84         directory no index
85
86         location "/.well-known/acme-challenge/*" {
87                 root "/acme"
88                 request strip 2
89         }
90
91         location "/robots.txt" { root "/htdocs/local/" }
92         location "/*" { block return 302 "https://$HTTP_HOST$REQUEST_URI" }
93 }
94
95 types {
96 }
97 ```
98 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.
99
100 Create the /var/www/htdocs/local/ folder and write the content of your robots.txt in /var/www/htdocs/local/robots.txt.
101 Check the configuration with `httpd -n`, if it is OK enable and start httpd (as root):
102 ```
103 rcctl enable httpd
104 rcctl start httpd
105 ```
106
107 #### acme-client
108 acme-client is used to get SSL/TLS certificates from Let's Encrypt.
109 Insert the following configuration in /etc/acme-client.conf:
110 ```
111 #
112 # $OpenBSD: acme-client.conf,v 1.4 2017/03/22 11:14:14 benno Exp $
113 #
114
115 authority letsencrypt-<domain name> {
116         #agreement url "https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf"
117         api url "https://acme-v02.api.letsencrypt.org/directory"
118         account key "/etc/acme/letsencrypt-privkey-<domain name>.pem"
119 }
120
121 domain <domain name> {
122         domain key "/etc/ssl/private/<domain name>.key"
123         domain certificate "/etc/ssl/<domain name>.crt"
124         domain full chain certificate "/etc/ssl/<domain name>.fullchain.pem"
125         sign with letsencrypt-<domain name>
126         challengedir "/var/www/acme/"
127 }
128 ```
129 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.
130 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`.
131
132 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:
133 ```
134 ln -s /etc/ssl/<domain name>.fullchain.pem /etc/ssl/<IP address>.crt
135 ln -s /etc/ssl/private/<domain name>.key /etc/ssl/private/<IP address>.key
136 ```
137 This will have to be done for each IPv4 and IPv6 address relayd listens on.
138
139 #### relayd
140 relayd will be used as the reverse proxy sitting in front of pleroma.
141 Insert the following configuration in /etc/relayd.conf:
142 ```
143 # $OpenBSD: relayd.conf,v 1.4 2018/03/23 09:55:06 claudio Exp $
144
145 ext_inet="<IPv4 address>"
146 ext_inet6="<IPv6 address>"
147
148 table <pleroma_server> { 127.0.0.1 }
149 table <httpd_server> { 127.0.0.1 }
150
151 http protocol plerup { # Protocol for upstream pleroma server
152         #tcp { nodelay, sack, socket buffer 65536, backlog 128 } # Uncomment and adjust as you see fit
153         tls ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
154         tls ecdhe secp384r1
155
156         # Forward some paths to the local server (as pleroma won't respond to them as you might want)
157         pass request quick path "/robots.txt" forward to <httpd_server>
158
159         # Append a bunch of headers
160         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
161         match request header append "X-Forwarded-By" value "$SERVER_ADDR:$SERVER_PORT"
162
163         match response header append "X-XSS-Protection" value "1; mode=block"
164         match response header append "X-Permitted-Cross-Domain-Policies" value "none"
165         match response header append "X-Frame-Options" value "DENY"
166         match response header append "X-Content-Type-Options" value "nosniff"
167         match response header append "Referrer-Policy" value "same-origin"
168         match response header append "X-Download-Options" value "noopen"
169         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
170         match request header append "Connection" value "upgrade"
171         #match response header append "Strict-Transport-Security" value "max-age=31536000; includeSubDomains" # Uncomment this only after you get HTTPS working.
172
173         # If you do not want remote frontends to be able to access your Pleroma backend server, comment these lines
174         match response header append "Access-Control-Allow-Origin" value "*"
175         match response header append "Access-Control-Allow-Methods" value "POST, PUT, DELETE, GET, PATCH, OPTIONS"
176         match response header append "Access-Control-Allow-Headers" value "Authorization, Content-Type, Idempotency-Key"
177         match response header append "Access-Control-Expose-Headers" value "Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id"
178         # Stop commenting lines here
179 }
180
181 relay wwwtls {
182         listen on $ext_inet port https tls # Comment to disable listening on IPv4
183         listen on $ext_inet6 port https tls # Comment to disable listening on IPv6
184
185         protocol plerup
186
187         forward to <pleroma_server> port 4000 check http "/" code 200
188         forward to <httpd_server> port 80 check http "/robots.txt" code 200
189 }
190 ```
191 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\>*.
192 Check the configuration with `relayd -n`, if it is OK enable and start relayd (as root):
193 ```
194 rcctl enable relayd
195 rcctl start relayd
196 ```
197
198 ##### (Strongly recommended) serve media on another domain
199
200 Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors.
201
202 #### pf
203 Enabling and configuring pf is highly recommended.
204 In /etc/pf.conf, insert the following configuration:
205 ```
206 # Macros
207 if="<network interface>"
208 authorized_ssh_clients="any"
209
210 # Skip traffic on loopback interface
211 set skip on lo
212
213 # Default behavior
214 set block-policy drop
215 block in log all
216 pass out quick
217
218 # Security features
219 match in all scrub (no-df random-id)
220 block in log from urpf-failed
221
222 # Rules
223 pass in quick on $if inet proto icmp to ($if) icmp-type { echoreq unreach paramprob trace } # ICMP
224 pass in quick on $if inet6 proto icmp6 to ($if) icmp6-type { echoreq unreach paramprob timex toobig } # ICMPv6
225 pass in quick on $if proto tcp to ($if) port { http https } # relayd/httpd
226 pass in quick on $if proto tcp from $authorized_ssh_clients to ($if) port ssh
227 ```
228 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 example, your home IP address, to avoid SSH connection attempts from bots.
229
230 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`.
231
232 #### Configure and start pleroma
233 Enter a shell as \_pleroma (as root `su _pleroma -`) and enter pleroma's installation directory (`cd ~/pleroma/`).
234
235 Then follow the main installation guide:
236
237   * run `mix deps.get`
238   * run `MIX_ENV=prod mix pleroma.instance gen` and enter your instance's information when asked
239   * 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.
240   * exit your current shell back to a root one and run `psql -U postgres -f /home/_pleroma/pleroma/config/setup_db.psql` to setup the database.
241   * return to a \_pleroma shell into pleroma's installation directory (`su _pleroma -;cd ~/pleroma`) and run `MIX_ENV=prod mix ecto.migrate`
242
243 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.
244 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.
245
246 ##### Starting pleroma at boot
247 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).
248
249
250 #### Create administrative user
251
252 If your instance is up and running, you can create your first user with administrative rights with the following command as the \_pleroma user.
253 ```
254 LC_ALL=en_US.UTF-8 MIX_ENV=prod mix pleroma.user new <username> <your@emailaddress> --admin
255 ```
256
257 #### Further reading
258
259 {! backend/installation/further_reading.include !}
260
261 ## Questions
262
263 Questions about the installation or didn’t it work as it should be, ask in [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) via Matrix or **#pleroma** on **libera.chat** via IRC.