# 🛰️ Orbit Server for gemini protocol written in PHP ## Dependencies - PHP 7.x or higher - composer (see getcomposer.org for download/install instructions) For dev dependencies: - php-xml - php-mbstring You can install PHP + required dev extensions on debian-based linux with ``` sudo apt install php-cli php-xml php-mbstring ``` ## Installation Clone this repository to a suitable location. ``` git clone https://tildegit.org/sumpygump/orbit.git ``` Fetch composer dependencies. ``` cd orbit composer update ``` You can choose to do `composer update --no-dev` to not include the dev dependencies (to run unit tests). ## Setup After installation, you can invoke the service with `bin/orbit`. You should pass in some important configuration options. See the configuration section below for more details. ### Quickstart For a quickstart, you can do the following: ``` sudo mkdir /var/gemini sudo sh -c 'echo "# Hello world\n\nServer is running" > /var/gemini/index.gmi' bin/orbit -c config/localhost.ini --dev ``` This will create a new directory to be the root of your gemini server at `/var/gemini`. Then we create an example index file at the root of the server. Then we run orbit pointing to the config file at `config/localhost.ini`. Running orbit with the `--dev` flag will automatically create the server key and cert files. ### Install as service To install as a service on your GNU/Linux machine, take a look at the `orbit.service` file in this repository. An accompanied Makefile in this repository will assist you in setting up as a service (only works on GNU/Linux). Change "localhost" in the command below to whatever the hostname for your server should be. ``` sudo make install ORBIT_HOSTNAME=localhost ``` This will perform the following steps: - Symlink the orbit bin script at `/usr/local/bin/orbit` - Create config file at `/etc/orbit/config.ini` - Create self-signed cert for you at `/etc/orbit/certs` - Create a new non-login user `gemini-data` for the service to use - Create service file at `/etc/systemd/system/orbit.service` Once this completes successfully, you may edit the config file to your liking, or install your own cert files. The default location of the server root is `/var/gemini`. To start the service run `sudo systemctl start orbit` or `sudo service orbit start` ## Usage Run `bin/orbit --help` to get some helpful command line invocation options. ``` $ bin/orbit --help Orbit 0.4 Usage: orbit [options] Options: -c, --config Use specified config file (.ini) for configuration --host Set host/ip address to listen on (default 0.0.0.0) -p, --port Set port to listen on (default 1965) --hostname Set hostname of server (default localhost) --tls-cert Set cert PEM file to use (default null) --tls-key Set private key PEM file to use (default null) --tls-passphrase Set passphrase for private key --root-dir Set the file root directory --log Set log filename (default orbit.log) --dev Allow developer server functions (default false) -h, --help Show help -v, --verbose Include more verbose output -q, --quiet Print less messages --no-color Don't use color output --version Show version and exit ``` ## Configuration Most configuration options are available to be set at the invocation of orbit. The option `-c` allows you to define a path to a config file to define any configuration options not specified as command arguments. ``` ; Example Orbit config file ; Host : The IP address designation that orbit should listen on host = "0.0.0.0" ; Port : the port that orbit should listen on port = 1965 ; Hostname : the expected domain that orbit is serving hostname = "example.com" ; TLS cert file : The location to the cert file tls_certfile = "/etc/orbit/example.com.cert.pem" ; TLS key file : The location to the private key for the server tls_keyfile = "/etc/orbit/example.com.key.pem" ; Key passphrase : optional passphrase for server key key_passphrase = "" ; Log file : where orbit should log information log_file = "/var/log/orbit/orbit.log" ; Log level : Only log messages that are at or above this level ; Possible values (from low to high): ; - debug ; - info ; - notice ; - warning ; - error ; - critical ; - alert ; - emergency log_level = "info" ; Root dir : Root directory of the server files root_dir = "/var/gemini" ; Index file : Name of the index file (when a directory is accessed) index_file = "index.gmi" ; Enable directory index : Whether orbit should serve up a directory listing ; for directories accessed that have no index file present enable_directory_index = true ``` ### Host The host config option is the IP address the server should bind to. Examples include 0.0.0.0 (to listen on all ipv4 addresses), or [::] to listen on all ipv6 addresses. In a config file, the option is specified with `host = "0.0.0.0"`. From the command line arguments, the option is specified with `--host 0.0.0.0` ### Port The port config option is which port the server will listen for incoming connections. The default for gemini is 1965, but orbit can be bound to any port that is available. If the port is not available, you will see the following error message "Exception: Error 0: Address already in use" In a config file, the option is specified with `port = 1965`. In command line arguments, the option is specified with `--port 1965` ### Hostname The hostname config option tells orbit which hostname the server is serving. It will deny requests that do match this domain. Config file option: `hostname = localhost`. Command line arg: `--hostname localhost` ### TLS cert file The TLS cert file config option allows you to define the path to the cert file in PEM format. Config file option: `tls_certfile = "/path/to/cert.pem"`. Command line arg: `--tls-cert /path/to/cert.pem`. ### TLS key file The TLS key file config option allows you to define the path to the private key file for the server in PEM format. Config file option: `tls_keyfile = "/path/to/key.pem"`. Command line arg: `--tls-key /path/to/key.pem`. ### Key passphrase If the private key requires a passphrase, you can specifiy it in the config option. Config file option: `key_passphrase = "secret"`. Command line arg: `--tls-passphrase secret`. ### Log file The log file config option allows you to define the location where the orbit log file should write to. It must be writable by the user used to launch orbit. Config file option: `log_file = "/path/to/orbit.log"`. Command line arg: `--log path/to/orbit.log`. ### Log level The log level config option allows you to specify the log level of the messages written to stdout or the log file. The levels are debug, info, notice, warning, error, critical, alert, emergency. Only log messages at or above the level specified will be include. Config file option: `log_level = "info"`. It is not possible to set granular levels with the command line arguments. The default is 'info'. If you use the `-v` or `--verbose` option, it will set the log level to 'debug'. ### Root directory The root directory config option allows you to specify the path that is the root directory of the server. Config file option: `root_dir = "/var/gemini"`. Command line arg: `--root-dir /var/gemini`. ### Index file If a request is made for a directory, orbit will look in the directory for the index file and serve it. Define what the name of this file will be by setting the index file config option. The default is "index.gmi". Config file option: `index_file = "index.gmi"`. ### Enable directory index If a request is made for a directory and there is no index file in the target directory, orbit can optionally return a list of files/directories within that directory. To turn this on, set the enable directory index config option. The default is to for this to be enabled. Config file option: `enable_directory_index = true`. ### `--dev` option The `--dev` command line argument flag tells orbit that this is a development server environment. When this is enabled, orbit will automatically create a self-signed cert at runtime. ### `-q / --quiet` option The `--quiet` command line argument flag tells orbit to not output anything to stdout.