CLI
Core is the process that does the routing. The desktop app starts and stops it for you. Run it yourself to validate a profile, to run Specola on a machine without a desktop, or to debug a start-up problem.
| Platform | Binary |
|---|---|
| Windows | specola-service.exe |
| macOS, Linux | specola-core |
specola-core --test-config --config home.toml # validate and exit
specola-core --config home.toml # run with this profile
specola-core # run and wait for the app to choose a profileOn Windows, write specola-service.exe instead of specola-core. Started without any argument, the Windows binary prints a hint and exits with code 1; use --console to run it with no other option.
Options
| Option | Platforms | Meaning |
|---|---|---|
--config <file> | all | the profile to load at start |
--test-config, -t | all | load and validate --config, print the result, exit; Core does not start |
--ipc-endpoint <path> | all | listen on another local control endpoint (below) |
--parent-pid <pid> | all | exit when that process exits; the desktop app passes its own PID. --parent-id is an old alias |
--gateway <file> | Linux | router mode (below) |
--console | Windows | run in the foreground from a terminal; has no other effect |
--service | Windows | run as the Windows service; only the Service Control Manager uses it |
--reset-network | Windows | remove the DNS redirect a killed Core left behind, then exit; needs Administrator |
-h, --help | all | print the options and exit |
-v, --version | all | print the version and exit |
- A value can follow the option (
--config home.toml) or be joined with=(--config=home.toml). - Options are exact: an unknown or misspelled option prints
Unknown argument, the help, and exits with code 1.-tcannot be combined with other short flags. - There is no option for a data directory or a portable mode, and no way to set the log level on the command line; Core uses the folders listed under Files and folders.
--config
specola-core --config /home/me/profiles/home.toml # absolute path
specola-core --config home.toml # file nameA relative path is looked up in this order:
- the Profiles folder (
~/.config/specola/profiles/home.tomlon Linux), - the folder of the executable.
The current directory is never used: specola-core --config ./home.toml run from your profile folder fails unless the file is also in one of those two places. Use an absolute path for a file elsewhere.
Inside the profile, relative paths of resource files (rule sets, geoip.dat, certificates) are resolved from the profile's own folder first; see Rules.
If the profile fails to load at a normal start, Core keeps running, reports the error to the app and the log, and waits for another profile. It does not exit.
--test-config
specola-core -t --config home.toml- Prints
Config validation passed: <path>and exits with 0, or printsConfig validation failed:followed by every error and exits with 1. - Warnings, such as ignored sections, go to the log, not to the terminal.
- It loads the profile exactly like a start: modules and disabled rules are applied, local resource files must exist, and remote rule sets and geo files are downloaded. When a download fails and a cached copy exists, the cached copy is used.
- It needs no administrator rights and does not touch the network setup, so it is safe to run while another Core is running.
- Without
--configit exits with 2.
Local control endpoint
The app controls Core over a local channel. It is always open while Core runs.
| Platform | Default endpoint | Who can connect |
|---|---|---|
| Windows | named pipe \\.\pipe\specola | the user who started Core; when Core runs as the service or elevated, also SYSTEM, Administrators and every signed-in user |
| macOS, Linux | Unix socket /tmp/specola.sock | the user who started Core (file mode 0600); when Core runs as root, the user who asked for root |
--ipc-endpoint changes it. It takes a socket path (/run/me/specola.sock), a pipe (\\.\pipe\name), or the URL forms unix:///path and pipe://name. The app must be pointed at the same endpoint.
Core is one instance per computer: a second Core exits with code 3 (Another specola-core process is already running). The control protocol is described in Control API; the optional TCP listener is api-listen.
Administrator rights
Enhanced Mode needs administrator (root) rights. On macOS and Linux, a Core started without them for a profile that enables Enhanced Mode asks for them once and starts again:
| Build | How Core asks |
|---|---|
| Linux release | pkexec, which shows the desktop's authentication dialog |
| macOS release | the system administrator prompt; output goes to core-privileged-launch.log in the log folder |
| debug builds | sudo in the terminal; with no terminal Core exits with code 1 |
Declining exits Core. On Windows the app starts Core through the service, which runs as LocalSystem.
Windows service
The installer registers a service named specola-service (display name "Specola Service"):
- It runs
specola-service.exe --serviceas LocalSystem, with manual start: the app starts it when it needs Core. Signed-in users may start, stop and query it; only administrators may change it. - It keeps its data in
%ProgramData%\Specola, readable only by SYSTEM and Administrators. Profiles stay in each user's own folder; the app tells the service where they are. - When the service process ends without stopping properly (killed, crashed), Windows runs
specola-service.exe --reset-network, which removes the NRPT rule that pointed system DNS at the TUN adapter. The service is not restarted.
Run --reset-network yourself from an Administrator terminal if DNS stops working after Core was killed:
& "C:\Program Files\Specola\specola-service.exe" --reset-networkIt exits with 0 when the rule is gone (or there was none) and with 1 without Administrator rights.
Router mode
Linux builds can run Core as a transparent gateway for a LAN:
specola-core --gateway /etc/specola/gateway.toml --config /etc/specola/profiles/router.toml
specola-core -t --gateway /etc/specola/gateway.toml # validate the gateway file onlyThe gateway file configures the LAN interfaces, TPROXY capture, DHCP, the LAN DNS server and the control listener (lan-interfaces, local-domain, device, tproxy, dhcp, dns, api). Unless [api] enable = false, Core opens a control listener on the first LAN interface's IPv4 address, port 9090 (or [api] listen), before any profile loads, so a remote app can choose one. Like api-listen, it serves only private-network peers and has no authentication. A gateway file that does not load makes Core exit with code 2.
Files and folders
| Windows | macOS | Linux | |
|---|---|---|---|
| Data | %LOCALAPPDATA%\Specola | ~/Library/Application Support/com.specola.Specola | $XDG_CONFIG_HOME/specola (~/.config/specola) |
| Profiles | <data>\profiles | <data>/profiles | <data>/profiles |
| Logs | <data>\Logs | ~/Library/Logs/com.specola.Specola | $XDG_STATE_HOME/specola/log (~/.local/state/specola/log) |
| Download cache | <data>\Cache\remote | ~/Library/Caches/com.specola.Specola/remote | $XDG_CACHE_HOME/specola/remote (~/.cache/specola/remote) |
As the Windows service, the data folder is %ProgramData%\Specola and there is no Profiles folder of its own. When Core runs as root on macOS or Linux, the folders are those of the user who asked for root, not of root.
Release builds write nothing to the terminal after start-up: messages such as Cannot find --config go to the log file only. Look there when Core exits without a message. Debug builds also print to the terminal and keep a single specola.log that is overwritten at every start.
Environment variables
| Variable | Effect |
|---|---|
SPECOLA_LOG_DIR | writes logs to this folder instead of the default log folder |
XDG_CONFIG_HOME, XDG_CACHE_HOME, XDG_STATE_HOME | Linux: move the data, cache and log folders; only absolute paths count |
XDG_RUNTIME_DIR | Linux: folder for runtime files, when it belongs to the user |
LOCALAPPDATA | Windows: an absolute path replaces the user's Local AppData folder (used by tests) |
When Core asks for root itself, it passes these variables on to the new process.
Stopping Core
Ctrl+C, SIGTERM and closing the console window stop Core gracefully: Enhanced Mode is taken down and system DNS restored. If shutdown takes longer than 10 seconds, Core exits anyway. With --parent-pid, Core also stops when that process ends.
Exit codes
| Code | Meaning |
|---|---|
0 | normal stop, --help, --version, a passed --test-config, a successful --reset-network |
1 | --test-config found errors; an unknown option or a missing value; the local control endpoint could not be opened; the gateway could not start; Windows: no argument given, --reset-network failed or lacks Administrator rights; macOS/Linux: asking for administrator rights failed |
2 | Core's folders could not be created; --config not found; --test-config without --config; an invalid --parent-pid, or that process could not be watched; the --gateway file did not load |
3 | another Core is already running on this computer |
4 | the single-instance lock could not be taken for another reason |
A profile that fails to load is not an exit: Core keeps running and waits for another one.
