Skip to content
English下载

CLI ​

Core 是负责分流的进程,平时由桌面应用替你启动和停止。需要校验 Profile、在没有桌面的机器上运行 Specola, 或排查启动问题时,可以自己运行它。

平台可执行文件
Windowsspecola-service.exe
macOS、Linuxspecola-core
bash
specola-core --test-config --config home.toml   # 校验后退出
specola-core --config home.toml                 # 用这个 Profile 运行
specola-core                                    # 运行,等待应用选择 Profile

Windows 上把 specola-core 换成 specola-service.exe。Windows 版不带任何参数启动时只打印一行提示, 并以退出码 1 退出;不需要其他选项时请加 --console。

选项 ​

选项平台作用
--config <文件>全部启动时加载的 Profile
--test-config、-t全部加载并校验 --config,打印结果后退出,不启动 Core
--ipc-endpoint <路径>全部改用其他本地控制端点(见下文)
--parent-pid <pid>全部该进程退出时 Core 也退出;桌面应用会传入自己的 PID。--parent-id 是旧别名
--gateway <文件>Linux路由器模式(见下文)
--consoleWindows在终端前台运行;没有其他作用
--serviceWindows作为 Windows 服务运行,只供服务控制管理器使用
--reset-networkWindows清除被强行结束的 Core 遗留的 DNS 重定向后退出;需要管理员权限
-h、--help全部打印选项后退出
-v、--version全部打印版本后退出
  • 选项的值可以跟在后面(--config home.toml),也可以用 = 连写(--config=home.toml)。
  • 选项必须完全匹配:未知或拼错的选项会打印 Unknown argument 和帮助,并以退出码 1 退出。 -t 不能和其他短选项合写。
  • 没有指定数据目录或便携模式的选项,也不能在命令行设置日志级别;Core 使用文件和目录 里列出的位置。

--config ​

bash
specola-core --config /home/me/profiles/home.toml   # 绝对路径
specola-core --config home.toml                     # 文件名

相对路径按以下顺序查找:

  1. Profiles 目录(Linux 上是 ~/.config/specola/profiles/home.toml);
  2. 可执行文件所在目录。

不会在当前目录查找:在 Profile 所在目录里运行 specola-core --config ./home.toml,只要这个文件不在上面两个 位置,就会失败。其他位置的文件请写绝对路径。

Profile 里资源文件(规则集、geoip.dat、证书)的相对路径,优先相对于 Profile 自己所在的目录, 见分流规则。

正常启动时 Profile 加载失败,Core 不会退出:它继续运行,把错误报告给应用并写入日志,等待选择另一个 Profile。

--test-config ​

bash
specola-core -t --config home.toml
  • 校验通过时打印 Config validation passed: <路径>,退出码 0;失败时打印 Config validation failed: 和全部错误,退出码 1。
  • 告警(例如被忽略的配置段)写入日志,不打印到终端。
  • 加载方式和正式启动完全一样:会应用模块和停用的规则,本地资源文件必须存在,远程规则集和 geo 文件会下载。 下载失败但有缓存时使用缓存。
  • 不需要管理员权限,不改动网络设置,另一个 Core 正在运行时也可以放心使用。
  • 不带 --config 时以退出码 2 退出。

本地控制端点 ​

应用通过本地通道控制 Core。Core 运行期间它始终打开。

平台默认端点谁能连接
Windows命名管道 \\.\pipe\specola启动 Core 的用户;Core 以服务或管理员身份运行时,还包括 SYSTEM、Administrators 和所有已登录用户
macOS、LinuxUnix socket /tmp/specola.sock启动 Core 的用户(文件权限 0600);Core 以 root 运行时,是申请 root 的那个用户

--ipc-endpoint 可以修改它,接受 socket 路径(/run/me/specola.sock)、管道(\\.\pipe\name), 或 unix:///path、pipe://name 这样的 URL 写法。应用也必须指向同一个端点。

一台电脑只能运行一个 Core:第二个 Core 会以退出码 3 退出(Another specola-core process is already running)。 控制协议见控制接口;可选的 TCP 监听见 api-listen。

管理员权限 ​

增强模式需要管理员(root)权限。在 macOS 和 Linux 上,如果没有权限的 Core 启动时加载的 Profile 开启了增强模式, 它会申请一次权限,然后重新启动自己:

版本申请方式
Linux 正式版pkexec,弹出桌面的认证对话框
macOS 正式版系统的管理员授权框;输出写入日志目录下的 core-privileged-launch.log
调试版在终端里用 sudo;没有终端时以退出码 1 退出

拒绝授权则 Core 退出。在 Windows 上,应用通过以 LocalSystem 运行的服务启动 Core。

Windows 服务 ​

安装程序会注册一个名为 specola-service 的服务(显示名称 “Specola Service”):

  • 它以 LocalSystem 身份运行 specola-service.exe --service,启动类型为手动:应用需要 Core 时才启动它。 已登录用户可以启动、停止和查询它,只有管理员能修改它。
  • 它的数据放在 %ProgramData%\Specola,只有 SYSTEM 和 Administrators 能访问。Profile 仍在各用户自己的目录里, 由应用告诉服务位置。
  • 服务进程没有正常停止就结束时(被强行结束、崩溃),Windows 会运行 specola-service.exe --reset-network, 删除把系统 DNS 指向 TUN 网卡的 NRPT 规则。服务本身不会被重启。

如果 Core 被强行结束后 DNS 不能用,可以在管理员终端里自己运行 --reset-network:

powershell
& "C:\Program Files\Specola\specola-service.exe" --reset-network

规则已删除(或本来就没有)时退出码为 0,没有管理员权限时为 1。

路由器模式 ​

Linux 版可以把 Core 作为局域网的透明网关运行:

bash
specola-core --gateway /etc/specola/gateway.toml --config /etc/specola/profiles/router.toml
specola-core -t --gateway /etc/specola/gateway.toml   # 只校验网关文件

网关文件配置局域网网卡、TPROXY 接管、DHCP、局域网 DNS 服务和控制监听(lan-interfaces、local-domain、 device、tproxy、dhcp、dns、api)。除非写了 [api] enable = false,Core 会在加载任何 Profile 之前, 在第一块局域网网卡的 IPv4 地址的 9090 端口(或 [api] listen 指定的地址)打开控制监听,让远程应用选择 Profile。 它和 api-listen 一样只服务私有网络的客户端,没有认证。网关文件加载失败时 Core 以退出码 2 退出。

文件和目录 ​

WindowsmacOSLinux
数据%LOCALAPPDATA%\Specola~/Library/Application Support/com.specola.Specola$XDG_CONFIG_HOME/specola(~/.config/specola)
Profiles<数据>\profiles<数据>/profiles<数据>/profiles
日志<数据>\Logs~/Library/Logs/com.specola.Specola$XDG_STATE_HOME/specola/log(~/.local/state/specola/log)
下载缓存<数据>\Cache\remote~/Library/Caches/com.specola.Specola/remote$XDG_CACHE_HOME/specola/remote(~/.cache/specola/remote)

作为 Windows 服务运行时,数据目录是 %ProgramData%\Specola,没有自己的 Profiles 目录。在 macOS 和 Linux 上以 root 运行时,使用的是申请 root 的那个用户的目录,而不是 root 的。

正式版启动后不向终端输出任何内容:Cannot find --config 这类消息只写进日志文件。Core 没有任何提示就退出时, 请去看日志。调试版还会打印到终端,并且只保留一个 specola.log,每次启动时覆盖。

环境变量 ​

变量作用
SPECOLA_LOG_DIR日志写到这个目录,而不是默认日志目录
XDG_CONFIG_HOME、XDG_CACHE_HOME、XDG_STATE_HOMELinux:改变数据、缓存和日志目录;只认绝对路径
XDG_RUNTIME_DIRLinux:运行时文件目录,需属于当前用户
LOCALAPPDATAWindows:绝对路径会替代用户的 Local AppData 目录(测试用)

Core 自己申请 root 时,会把这些变量传给新进程。

停止 Core ​

Ctrl+C、SIGTERM 和关闭控制台窗口都会让 Core 正常停止:撤下增强模式并恢复系统 DNS。 停止过程超过 10 秒时,Core 会直接退出。带 --parent-pid 时,那个进程结束 Core 也会停止。

退出码 ​

退出码含义
0正常停止、--help、--version、--test-config 通过、--reset-network 成功
1--test-config 发现错误;未知选项或缺少值;本地控制端点打不开;网关无法启动;Windows:不带任何参数、--reset-network 失败或没有管理员权限;macOS/Linux:申请管理员权限失败
2Core 的目录无法创建;找不到 --config;--test-config 没有 --config;--parent-pid 无效或无法监视该进程;--gateway 文件加载失败
3这台电脑上已经有一个 Core 在运行
4因其他原因拿不到单实例锁

Profile 加载失败不会导致退出:Core 继续运行,等待选择另一个 Profile。