1 7c6bf71d 2021-10-11 op => / Home
  2 8af884df 2021-10-11 op => contrib.gmi contrib
  3 7c6bf71d 2021-10-11 op => /gmid.1.txt docs
  4 7c6bf71d 2021-10-11 op 
  5 0111ad5d 2021-10-09 op # gmid quickstart
  6 0111ad5d 2021-10-09 op 
  7 0111ad5d 2021-10-09 op gmid can be run in two different “modes”:
  8 0111ad5d 2021-10-09 op 
  9 0111ad5d 2021-10-09 op * configless: a quick way to serve a directory tree from the shell, useful for testing a capsule before uploading it
 10 0111ad5d 2021-10-09 op * daemon mode: gmid reads the configuration file and runs in the background
 11 0111ad5d 2021-10-09 op 
 12 0111ad5d 2021-10-09 op To run gmid in the “configless” mode, just type:
 13 0111ad5d 2021-10-09 op 
 14 0111ad5d 2021-10-09 op ```serve a directory tree from the shell
 15 0111ad5d 2021-10-09 op $ gmid path/to/dir
 16 0111ad5d 2021-10-09 op ```
 17 0111ad5d 2021-10-09 op 
 18 540d05de 2021-10-09 op gmid will then generate a certificate inside ~/.local/share/gmid and serve the given directory locally.
 19 0111ad5d 2021-10-09 op 
 20 fc4b58d4 2021-10-11 op ## Setting up a capsule with gmid
 21 0111ad5d 2021-10-09 op 
 22 fc4b58d4 2021-10-11 op To host a Gemini capsule you need to run gmid in “daemon” mode.
 23 fc4b58d4 2021-10-11 op 
 24 fc4b58d4 2021-10-11 op To run gmid in daemon mode a configuration file is needed.  The format of the configuration file is described in the manpage and is quite flexible, but something like the following should be enough to start:
 25 fc4b58d4 2021-10-11 op 
 26 0111ad5d 2021-10-09 op ```sample configuration file
 27 0111ad5d 2021-10-09 op # /etc/gmid.conf
 28 0111ad5d 2021-10-09 op 
 29 0111ad5d 2021-10-09 op server "example.com" {
 30 0111ad5d 2021-10-09 op 	cert "/path/to/certificate"
 31 0111ad5d 2021-10-09 op 	key  "/path/to/private-key"
 32 0111ad5d 2021-10-09 op 	root "/var/gemini/example.com"
 33 0111ad5d 2021-10-09 op }
 34 0111ad5d 2021-10-09 op ```
 35 0111ad5d 2021-10-09 op 
 36 fc4b58d4 2021-10-11 op You also need to generate a certificate for the capsule.  A X.509 (TLS) certificate can be generated for e.g. with contrib/gencert
 37 0111ad5d 2021-10-09 op 
 38 0111ad5d 2021-10-09 op => https://git.omarpolo.com/gmid/tree/contrib/gencert contrib/gencert
 39 0111ad5d 2021-10-09 op 
 40 0111ad5d 2021-10-09 op ```generate a certificate using contrib/gencert
 41 0111ad5d 2021-10-09 op $ ./contrib/gencert example.com
 42 0111ad5d 2021-10-09 op Generating a 4096 bit RSA private key
 43 0111ad5d 2021-10-09 op .................................................++++
 44 0111ad5d 2021-10-09 op ..........++++
 45 0111ad5d 2021-10-09 op writing new private key to './example.com.key'
 46 0111ad5d 2021-10-09 op -----
 47 0111ad5d 2021-10-09 op 
 48 0111ad5d 2021-10-09 op Generated files:
 49 0111ad5d 2021-10-09 op         ./example.com.pem : certificate
 50 0111ad5d 2021-10-09 op         ./example.com.key : private key
 51 0111ad5d 2021-10-09 op ```
 52 0111ad5d 2021-10-09 op 
 53 35340c9f 2021-10-09 op Optionally, move ‘example.com.pem’ and ‘example.com.key’ to another location.
 54 0111ad5d 2021-10-09 op 
 55 0111ad5d 2021-10-09 op Make sure that the ‘cert’ and ‘key’ options in the configuration file points to these files.
 56 0111ad5d 2021-10-09 op 
 57 0111ad5d 2021-10-09 op Then running gmid is as easy as
 58 0111ad5d 2021-10-09 op 
 59 0111ad5d 2021-10-09 op ```running gmid
 60 0111ad5d 2021-10-09 op $ gmid -c /etc/gmid.conf
 61 0111ad5d 2021-10-09 op ```
 62 0111ad5d 2021-10-09 op 
 63 fc4b58d4 2021-10-11 op Congratulations, your capsule is online!
 64 0111ad5d 2021-10-09 op 
 65 fc4b58d4 2021-10-11 op 
 66 0111ad5d 2021-10-09 op ## Securing your gmid installation
 67 0111ad5d 2021-10-09 op 
 68 0111ad5d 2021-10-09 op gmid employs various techniques to prevent the damage caused by bugs, but some steps needs to be done manually.
 69 0111ad5d 2021-10-09 op 
 70 0111ad5d 2021-10-09 op If gmid was installed from your distribution package manager, chance are that it already does all of this and is also providing a service to run gmid automatically (e.g. a systemd unit file, a rc script, …)  Otherwise, it’s heavily suggested to create at least a dedicated user.
 71 0111ad5d 2021-10-09 op 
 72 0111ad5d 2021-10-09 op 
 73 0111ad5d 2021-10-09 op ### A dedicated user
 74 0111ad5d 2021-10-09 op 
 75 fc4b58d4 2021-10-11 op Ideally, gmid should be started as root and drop privileges to a local user.  This way, the certificates can be readable only by root.  For example, on GNU/linux systems a ‘gmid’ user can be created with:
 76 0111ad5d 2021-10-09 op 
 77 0111ad5d 2021-10-09 op ```how to create the gmid user
 78 35340c9f 2021-10-09 op # useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid
 79 0111ad5d 2021-10-09 op ```
 80 0111ad5d 2021-10-09 op 
 81 0111ad5d 2021-10-09 op Please consult your OS documentation for more information on the matter.
 82 0111ad5d 2021-10-09 op 
 83 0111ad5d 2021-10-09 op The configuration then needs to be adjusted to include the ‘user’ directive at the top:
 84 0111ad5d 2021-10-09 op 
 85 0111ad5d 2021-10-09 op ```how to use the ‘user’ option
 86 0111ad5d 2021-10-09 op # /etc/gmid.conf
 87 0111ad5d 2021-10-09 op user "gmid"
 88 0111ad5d 2021-10-09 op 
 89 0111ad5d 2021-10-09 op server "example.com" { … }
 90 0111ad5d 2021-10-09 op ```
 91 0111ad5d 2021-10-09 op 
 92 fc4b58d4 2021-10-11 op gmid then needs to be started with root privileges, but will then switch to the provided user automatically.  If by accident the ‘user’ option is omitted and gmid is running as root, it will complain loudly in the logs.
 93 0111ad5d 2021-10-09 op 
 94 0111ad5d 2021-10-09 op 
 95 0111ad5d 2021-10-09 op ### chroot
 96 0111ad5d 2021-10-09 op 
 97 0111ad5d 2021-10-09 op It’s a common practice for system daemons to chroot themselves into a directory.  From here on I’ll assume /var/gemini, but it can be any directory.
 98 0111ad5d 2021-10-09 op 
 99 fc4b58d4 2021-10-11 op A chroot on UNIX-like OS is an operation that changes the “apparent” root directory (i.e. the “/”) from the current process and its child.  Think of it like imprisoning a process into a directory and never letting it escape until it terminates.
100 0111ad5d 2021-10-09 op 
101 fc4b58d4 2021-10-11 op Using a chroot may complicate the use of CGI scripts, because then all the dependencies of the scripts (sh, perl, libraries…) need to be installed inside the chroot too.  For this very reason gmid supports FastCGI.
102 0111ad5d 2021-10-09 op 
103 0111ad5d 2021-10-09 op The chroot feature requires a dedicate user, see the previous section.
104 0111ad5d 2021-10-09 op 
105 0111ad5d 2021-10-09 op To chroot gmid inside a directory, use the ‘chroot’ directive in the configuration file:
106 0111ad5d 2021-10-09 op 
107 0111ad5d 2021-10-09 op ```how to use the ‘chroot’ option
108 0111ad5d 2021-10-09 op # /etc/gmid.conf
109 0111ad5d 2021-10-09 op 
110 35340c9f 2021-10-09 op user "gmid"
111 35340c9f 2021-10-09 op 
112 0111ad5d 2021-10-09 op # the given directory, /var/gemini in this case, must exists.
113 0111ad5d 2021-10-09 op chroot "/var/gemini"
114 0111ad5d 2021-10-09 op ```
115 0111ad5d 2021-10-09 op 
116 0111ad5d 2021-10-09 op Note that once ‘chroot’ is in place, every ‘root’ directive is implicitly relative to the chroot, but ‘cert’ and ‘key’ aren’t!
117 0111ad5d 2021-10-09 op 
118 0111ad5d 2021-10-09 op For example, given the following configuration:
119 0111ad5d 2021-10-09 op 
120 0111ad5d 2021-10-09 op ```example configuration using chroot
121 0111ad5d 2021-10-09 op # /etc/gmid.conf
122 0111ad5d 2021-10-09 op 
123 0111ad5d 2021-10-09 op user "gmid"
124 0111ad5d 2021-10-09 op chroot "/var/gemini"
125 0111ad5d 2021-10-09 op 
126 0111ad5d 2021-10-09 op server "example.com" {
127 0111ad5d 2021-10-09 op 	cert "/etc/ssl/example.com.pem"
128 0111ad5d 2021-10-09 op 	key  "/etc/ssl/example.com.key"
129 0111ad5d 2021-10-09 op 	root "/example.com"
130 0111ad5d 2021-10-09 op }
131 0111ad5d 2021-10-09 op ```
132 0111ad5d 2021-10-09 op 
133 0111ad5d 2021-10-09 op The certificate and the key path are the specified ones, but the root directory of the virtual host is actually “/var/gemini/example.com/”.