README

用 PHP 编写的 gemini 协议服务器

依赖关系

• PHP 7.x 或更高版本
• composer（有关下载/安装说明，请参阅 getcomposer.org）

对于开发依赖项

• php-xml
• php-mbstring

您可以使用以下命令在基于 Debian 的 Linux 上安装 PHP 和所需的开发扩展：

sudo apt install php-cli php-xml php-mbstring

安装

将此存储库克隆到合适的位置。

git clone https://tildegit.org/sumpygump/orbit.git

获取 composer 依赖项。

cd orbit
composer update

您可以选择执行 composer update --no-dev 以不包括开发依赖项（以运行单元测试）。

设置

安装后，您可以使用 bin/orbit 调用服务。您应该传递一些重要的配置选项。有关更多详细信息，请参阅下面的配置部分。

快速入门

为了快速入门，您可以执行以下操作

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

这将创建一个新目录作为您的 gemini 服务器根目录 /var/gemini。然后我们在服务器根目录创建一个示例索引文件。然后我们运行指向配置文件 config/localhost.ini 的 orbit。使用 --dev 标志运行 orbit 将自动创建服务器密钥和证书文件。

作为服务安装

要在您的 GNU/Linux 机器上作为服务安装，请查看此存储库中的 orbit.service 文件。

此存储库中的附带 Makefile 可帮助您将其设置为服务（仅在 GNU/Linux 上有效）。将以下命令中的 "localhost" 更改为您的服务器应使用的任何主机名。

sudo make install ORBIT_HOSTNAME=localhost

这将执行以下步骤

• 在 /usr/local/bin/orbit 中创建 orbit bin 脚本的符号链接
• 在 /etc/orbit/config.ini 中创建配置文件
• 在 /etc/orbit/certs 中为您创建自签名证书
• 为服务创建一个新非登录用户 gemini-data
• 在 /etc/systemd/system/orbit.service 中创建服务文件

一旦成功完成，您可以按需编辑配置文件，或安装您自己的证书文件。服务器根目录的默认位置是 /var/gemini。

要启动服务，请运行 sudo systemctl start orbit 或 sudo service orbit start

用法

运行 bin/orbit --help 以获取一些有用的命令行调用选项。

$ bin/orbit --help
Orbit 0.4
Usage: orbit [options]

Options:
  -c, --config <arg>   Use specified config file (.ini) for configuration
      --host <arg>     Set host/ip address to listen on (default 0.0.0.0)
  -p, --port <arg>     Set port to listen on (default 1965)
      --hostname <arg> Set hostname of server (default localhost)
      --tls-cert <arg> Set cert PEM file to use (default null)
      --tls-key <arg>  Set private key PEM file to use (default null)
      --tls-passphrase <arg> Set passphrase for private key
      --root-dir <arg> Set the file root directory
      --log <arg>      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

配置

大多数配置选项都可以在调用 orbit 时设置。选项 -c 允许您定义一个路径到配置文件以定义任何未作为命令参数指定的配置选项。

; 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

主机

主机配置选项是服务器应绑定到的 IP 地址。示例包括 0.0.0.0（监听所有 ipv4 地址），或 [::] 以监听所有 ipv6 地址。

在配置文件中，选项指定为 host = "0.0.0.0"。从命令行参数指定，选项指定为 --host 0.0.0.0

端口

端口配置选项是服务器将监听传入连接的端口。gemini 的默认端口是 1965，但 orbit 可以绑定到任何可用的端口。

如果端口不可用，您将看到以下错误消息 "异常：错误 0：地址已在使用中"

在配置文件中，选项指定为 port = 1965。在命令行参数中，选项指定为 --port 1965

主机名

主机名配置选项告诉 orbit 服务器正在为哪个主机名提供服务。它将拒绝匹配此域的请求。

配置文件选项： hostname = localhost。命令行参数： --hostname localhost

TLS 证书文件

TLS证书文件配置选项允许您定义PEM格式的证书文件的路径。

配置文件选项：tls_certfile = "/path/to/cert.pem"。命令行参数：--tls-cert /path/to/cert.pem。

TLS密钥文件

TLS密钥文件配置选项允许您定义服务器私钥文件的路径，格式为PEM。

配置文件选项：tls_keyfile = "/path/to/key.pem"。命令行参数：--tls-key /path/to/key.pem。

密钥密码

如果私钥需要密码，您可以在配置选项中指定它。

配置文件选项：key_passphrase = "secret"。命令行参数：--tls-passphrase secret。

日志文件

日志文件配置选项允许您定义Orbit日志文件应该写入的位置。它必须是可以由启动Orbit的用户写入的。

配置文件选项：log_file = "/path/to/orbit.log"。命令行参数：--log path/to/orbit.log。

日志级别

日志级别配置选项允许您指定写入stdout或日志文件的日志级别。级别有：调试、信息、通知、警告、错误、严重、警报、紧急。只有达到或高于指定级别的日志消息会被包含。

配置文件选项：log_level = "info"。

无法通过命令行参数设置粒度级别。默认为'info'。如果使用-v或--verbose选项，将日志级别设置为'debug'。

根目录

根目录配置选项允许您指定服务器的根目录路径。

配置文件选项：root_dir = "/var/gemini"。命令行参数：--root-dir /var/gemini。

索引文件

如果请求一个目录，Orbit将在这个目录中查找索引文件并服务它。通过设置索引文件配置选项来定义此文件的名称。默认为"index.gmi"。

配置文件选项：index_file = "index.gmi"。

启用目录索引

如果请求一个目录且目标目录中没有索引文件，Orbit可以选择返回该目录中的文件/目录列表。要启用此功能，请设置启用目录索引配置选项。默认是启用。

配置文件选项：enable_directory_index = true。

--dev 选项

--dev 命令行参数标志告诉Orbit这是一个开发服务器环境。当启用时，Orbit将在运行时自动创建一个自签名的证书。

-q / --quiet 选项

--quiet 命令行参数标志告诉Orbit不要将任何内容输出到stdout。