Skip to content

Configuration reference ​

This page lists every setting an operator can make on a Felis host: the environment variables the installer reads, the sections and keys of felis.toml, the files under /etc/felis, and the settings saved in the panel together with their precedence. It is for operators who install, configure and maintain a host.

Where settings live ​

A Felis host has three layers of configuration:

  • Installer variables (FELIS_*) are read on every installer run. Most of them are recorded in the files they produce, so a later run keeps the result.
  • Host files under /etc/felis: the configuration file felis.toml and the files that hold credentials and installer records.
  • Settings saved in the panel, stored in the database. Where the panel and a host file configure the same thing, the panel's value takes precedence; see Panel settings and precedence.

Installer variables ​

Passing variables ​

Name each variable on the sudo line of the installer command:

bash
curl -fsSL https://raw.githubusercontent.com/FelisMC/Felis/main/deploy/bootstrap.sh \
  | sudo FELIS_VERSION_BOOTSTRAP=dev FELIS_VELOCITY_XMX=2G bash

sudo resets the environment, so a variable exported before sudo does not reach the installer. Either name it on the sudo line as above, or export it and run sudo -E bash.

Variables that apply only to the first install, or that later runs keep without being named again, say so in their description. A rerun reuses the generated credentials in /etc/felis/secrets.env and keeps the installed root domain. FELIS_VERSION_BOOTSTRAP, FELIS_GAME_PORT, FELIS_PANEL_NODEPORT and FELIS_WORLDS_HOST_PATH are recorded in /etc/felis/install.env: reruns and updates started from the panel use the recorded values, and a variable named for a run replaces its recorded value. The installer reads the file as plain KEY=value lines, checks each value as it checks the variable, and ignores any other line.

Install mode and channel ​

VariableDefaultDescription
FELIS_INSTALL_MODEAsk on a terminal, otherwise fullfull installs the whole platform. nano installs Felis-nano, which handles login control only and runs without k3s; see Felis-nano. On a host that runs Felis-nano and no full install, the default is nano.
FELIS_VERSION_BOOTSTRAPreleaserelease installs the newest published release from its assets, each checked against the release's SHA256SUMS. dev builds the newest main commit from source. Later runs keep the channel. To install a release with FELIS_RELEASE on a host that follows dev, also set FELIS_VERSION_BOOTSTRAP=release.
FELIS_RELEASENewest releaseA published release tag (v1.2.3) to install instead of the newest, from its assets. Use the installer of the same tag. This is the way back to an earlier release.
FELIS_REF—A branch, tag or commit to build from source. It overrides the channel.
FELIS_ARTIFACT_DIR—Absolute path of a directory holding a release's assets. The Felis binary, images and plugin are installed from there; nothing of Felis's own is downloaded or built, and a missing or mismatching file stops the install. Cannot be combined with FELIS_REF or FELIS_SKIP_FETCH.
FELIS_SKIP_FETCH—Build the source tree already present in /opt/felis/src without fetching it.
FELIS_REPO_URLhttps://github.com/FelisMC/Felis.gitGit repository to build from and to look up releases in.
FELIS_GITHUB_TOKEN—GitHub token, needed only to install from a private fork. Secret.
FELIS_FORCE_UPDATE—1 reinstalls the binary even when its version already matches.
FELIS_IGNORE_MAINTENANCE_WINDOW—1 lets an installer rerun on an installed host skip the maintenance window check. felis update --apply sets it for the installer it runs.
FELIS_IMAGEregistry.felis.svc:5000/felis/felis:<version>Control-plane image reference. An image outside the in-cluster registry is used as it is and is not copied into the registry.

See Release channels and Installing from downloaded assets.

Network and domain ​

VariableDefaultDescription
FELIS_ROOT_DOMAIN<host-address>.nip.io; <public-address>.nip.io on a cloud hostRoot domain of the install. First install only: a rerun keeps the installed domain and stops when given a different one. Move the domain with felis domain set.
FELIS_PUBLIC_IP—Public IPv4 address given to players and browsers: in the default root domain, the panel certificate and the addresses the installer prints. Unset, the installer looks it up over HTTPS when the host's own address is private and the host is a cloud host. none keeps the host's own address. The cluster and the firewall always use the host's own address. See Public address.
FELIS_PANEL_NODEPORT30443NodePort of the built-in HTTPS panel and API. Later runs keep it.
FELIS_GAME_PORT25565Port on which the game proxy accepts players. The panel adds it to server addresses when it is not 25565. Later runs keep it.

See Network and ports.

Access and Cloudflare ​

The access method (direct access, your own reverse proxy, or Cloudflare Tunnel with Access) has no installer variable. Choose it in the setup wizard or on Platform settings → Access and security; see Access methods. The installer variables for Cloudflare control the cloudflared binary:

VariableDefaultDescription
FELIS_CLOUDFLARED_VERSION2026.9.1cloudflared release installed when none is present. An installed cloudflared moves to it only with FELIS_UPGRADE_DEPS=1.
FELIS_CLOUDFLARED_SHA256Pinned for the default versionsha256 of that release for this architecture. Required for any other version.

Component versions ​

VariableDefaultDescription
FELIS_K3S_VERSIONv1.36.4+k3s1k3s release a fresh install gets. An installed k3s is left alone unless FELIS_UPGRADE_DEPS=1.
FELIS_UPGRADE_DEPS01 moves an installed k3s and cloudflared to the pinned versions (k3s one minor version at a time, never downgraded) and restarts cloudflared-felis on the new binary.
FELIS_JRE_VERSION25Temurin feature version the game proxy runs on. The default's build and digests are pinned; another feature version is checked against the digest Adoptium publishes.
FELIS_GO_VERSION1.27.4Go toolchain used to build the Felis-nano binary.
FELIS_GO_SHA256Pinned for the default versionsha256 of that Go release for this architecture. Required for any other version.

See Component versions.

Storage and backups ​

VariableDefaultDescription
FELIS_BACKUP_PVCfelis-backupsWorld archive volume. An empty value disables world backups; the backup endpoints then answer 503.
FELIS_ARCHIVE_LOCAL_PATH/var/lib/felis/archivesPath at which that volume is mounted inside backup Jobs. Written to [archive] local_path.
FELIS_WORLDS_HOST_PATHUnsetNode directory holding the world volumes (/var/lib/rancher/k3s/storage on the installer's k3s). When set, the daily reaper also archives and then deletes worlds idle for 15 days. When unset, worlds are never deleted and the reaper only removes expired backups. Later runs keep it; set it to an empty value to turn world cleanup off again. See World cleanup.
FELIS_REGISTRY_STORAGE10GiCapacity the registry volume requests. First install only; k3s local-path storage does not enforce it.
FELIS_UPLOADS_STORAGE5GiCapacity the uploads volume requests. First install only; not enforced.
FELIS_BACKUP_STORAGE10GiCapacity the world archive volume requests. First install only; not enforced.
FELIS_DB_BACKUP_DIR/var/lib/felis/db-backupsDirectory of the database bundles.
FELIS_DB_BACKUP_TIME*-*-* 03:30:00systemd calendar expression of the daily database backup; the timer adds up to 15 minutes of random delay. The panel can set it.
FELIS_DB_BACKUP_KEEP14Daily bundles kept. The panel can set it.
FELIS_DB_BACKUP_METRICS/var/lib/node_exporter/textfile_collector/felis_db_backup.promnode-exporter textfile that each daily backup rewrites.
FELIS_PRE_MIGRATE_BACKUP10 applies pending migrations without the pre-migration bundle. Use it only when that bundle cannot be taken and another backup exists.

See Database bundles and Disk layout.

Off-site copy ​

VariableDefaultDescription
FELIS_OFFSITE_ENDPOINT—https://host[:port] of the S3-compatible store. Required with a bucket.
FELIS_OFFSITE_BUCKET—Bucket name. Setting it turns the off-site copy on.
FELIS_OFFSITE_REGION—Bucket region.
FELIS_OFFSITE_PREFIX—Key prefix, so that one bucket can hold several installs.
FELIS_OFFSITE_DB_KEEP30Newest database bundles kept in the bucket.
FELIS_OFFSITE_ACCESS_KEY—Bucket access key. Secret; stored in /etc/felis/offsite.env.
FELIS_OFFSITE_SECRET_KEY—Bucket secret key. Secret; stored in /etc/felis/offsite.env.
FELIS_OFFSITE_KEYGeneratedEncryption key, as printed by felis offsite keygen. Secret. When none exists the installer generates one and shows it once on the terminal. A rerun refuses a key that differs from the one in offsite.env.
FELIS_RESTORE_FROM_OFFSITE—1 rebuilds this fresh host from the off-site copy once it is installed, by running felis restore-host. Requires FELIS_OFFSITE_ENDPOINT, FELIS_OFFSITE_BUCKET, FELIS_OFFSITE_ACCESS_KEY, FELIS_OFFSITE_SECRET_KEY and FELIS_OFFSITE_KEY.
FELIS_RESTORE_BUNDLENewest bundleBundle name (felis-db-<stamp>-<label>.tar) from felis offsite list to rebuild from.
FELIS_RESTORE_TAKE_OVER—1 makes this host the one that writes the bucket once rebuilt. Leave it unset on a rehearsal machine.

The values must not contain quotes, backslashes or line breaks. A rerun without these variables keeps the existing [offsite] section and offsite.env. See Off-site copy and The encryption key.

DANGER

Keep FELIS_OFFSITE_KEY somewhere other than the host. Without it, nothing in the bucket can be read.

Game stack and proxy ​

VariableDefaultDescription
FELIS_GAME_STACKpinnedpinned installs the Limbo, Paper, LuckPerms and Velocity builds the release pins, each checked against its sha256. latest resolves upstream's newest builds on every run and builds the game images on the host.
FELIS_VELOCITY_VERSIONThe pinned versionAnother Velocity version installs the newest build of that version.
FELIS_VELOCITY_XMX1G, 256M on the small-host profileMaximum heap of the game proxy, written <n>M or <n>G, at least 256M. Read on every run; a change restarts the proxy, which disconnects every player. The panel can set it.
FELIS_VELOCITY_FORK_JAR—Path to a Felis-Legacy Velocity fork build, installed as the proxy instead of stock Velocity.
FELIS_VELOCITY_FORK_JAR_SHA256—sha256 of that jar. Required when the jar is set; a mismatch stops the install.
FELIS_LEGACY_FORWARDING_SERVERSlegacy18Comma-separated servers that always receive the player's identity through the handshake address, in addition to servers set to legacy forwarding. See Forwarding mode.
FELIS_LIMBO_IMAGE, FELIS_LOBBY_IMAGE, FELIS_PAPER_IMAGEregistry.felis.svc:5000/felis/limbo:demo, …/lobby:demo, …/paper:demoImage references of the login space, the lobby and the Paper base image.
FELIS_NANO_LISTENThe address an installed felis-nano uses, else 127.0.0.1:8081Listen address of Felis-nano. Set a private-network address to serve a proxy on another host.
FELIS_NANO_PROXY_CIDR—The proxy allowed to reach a non-loopback Felis-nano, as an address with a prefix length (for example 10.0.0.7/32). The host firewall opens the port to that source only.
FELIS_NANO_PANEL_PORTThe port an installed felis-nano uses, else 8443HTTPS port of the Felis-nano panel.
FELIS_NANO_PUBLIC_PORTThe port an installed felis-nano uses, else the panel portPort in the Felis-nano panel's public address. Set 443 when a reverse proxy serves the panel on port 443; see Reverse proxy.

See Sizing for the proxy heap.

Monitoring ​

VariableDefaultDescription
FELIS_WATCHDOG_HEARTBEAT_URL—Heartbeat URL that each watchdog run pings. Written to /etc/felis/watchdog-heartbeat-url (mode 0600). off removes it; a rerun without the variable keeps it. Treat it as a secret: the URL's path is the check's key. A heartbeat saved in the panel takes precedence.

See External heartbeat.

Distributed mode and high availability ​

VariableDefaultDescription
FELIS_DISTRIBUTED0; a rerun detects an existing distributed controller1 enables distributed mode on the controller.
FELIS_NODE_EXTERNAL_IP—This node's fixed external address.
FELIS_PEER_CIDRSThe list last installedExact peer addresses (/32 or /128), comma-separated. A rerun without it keeps the list in /etc/felis/node-peers.
FELIS_CONTROLLER_HA—1 enables controller high availability. Requires FELIS_DISTRIBUTED=1. Later runs keep it through /etc/felis/ha.env.
FELIS_HA_VIP—Optional IPv4 floating address with prefix length, such as 192.0.2.50/24.
FELIS_HA_VIP_INTERFACEThe interface that carries the node addressNetwork interface of the floating address.
FELIS_HA_VRID51VRRP virtual router ID, 1–255.
FELIS_LONGHORN_VERSIONv1.8.1Longhorn version installed for replicated storage.

The installer's worker, controller-join and reconfigure modes are started by felis node, node operations and the panel, which set the variables those modes need. See Multi-node and high availability.

Preflight and setup ​

VariableDefaultDescription
FELIS_PREFLIGHTstrictstrict stops on any preflight problem and lists them all. warn reports them and installs anyway, for a host the checks misjudge.
FELIS_HOST_PROFILEautoHost profile. auto picks small for a fresh installation with less than 3.5 GiB of memory, and later runs keep the recorded profile; small deploys no lobby and shrinks the components' memory; standard is the standard profile. See Small hosts.
FELIS_WITH_LOBBYautoWhether to enable the lobby at install time. auto asks on an interactive fresh standard install whether to start the lobby (default N), defaults to 0 on a non-interactive fresh install, and on later runs keeps the value recorded in /etc/felis/with-lobby (1 on an existing install without the file); 0 creates the lobby stopped and leaves it disabled in the default entry policy; 1 starts it at install time. Refused with 1 on the small-host profile. Can be changed at any time under Player entry policy.
FELIS_NO_SETUP—1 ends a full install at its summary. Otherwise an install on a terminal that leaves no Owner continues into felis setup.
FELIS_MANAGE_TIME_SYNC10 leaves the host's clock alone. By default the installer turns NTP on, installing chrony when nothing else can, and waits for synchronization.
FELIS_MANAGE_JOURNAL10 leaves journald alone. By default the installer makes the system journal persistent.
FELIS_JOURNAL_MAX_USE1GSize cap of the persistent journal, written <n>K, <n>M or <n>G.
PKG_LOCK_TIMEOUT900Seconds to wait for package manager locks.

See Preflight checks.

felis.toml ​

The platform's configuration is a TOML file in two copies, both written by the installer:

  • /etc/felis/felis.host.toml, the host copy, read by commands on the host. It reaches the database on a loopback port.
  • /etc/felis/felis.pod.toml, the pod copy, stored in the felis-config Secret and read by the control plane.

/etc/felis/felis.toml is a link to the host copy and is the default -config of every felis command.

Editing rules ​

  • The installer regenerates both copies on every run. It carries forward the sections and keys an operator may edit: [auth], [smtp], [[auth_source]], [offsite], and the operator keys of [registry], [registry.s3] and [archive] listed below. Any other edit is overwritten.
  • To change a setting, edit /etc/felis/felis.host.toml, then rerun the installer, which carries the change into the pod copy and applies it.
  • Unknown keys are refused. A misspelt key stops every command that reads the file with config: unknown keys in <file>: <key>.
  • Time spans are written 90d (days), 3mo (months of 30 days), or a duration such as 12h or 10m. Sizes are written with Gi, Mi, Ki, G, M or K, or as a number of bytes.
  • [database] url contains the database password, so both copies are readable by root only. Every other credential is kept out of the file: a key ending in _ref names the environment variable that holds the value.

[auth] ​

KeyDefaultDescription
panel_hostnameconsole.<root domain>Hostname of the panel.
admin_hostnameop.console.<root domain>Hostname of the admin console.
access_jwt_aud—Audience of the Cloudflare Access application, written by the Cloudflare step of felis setup. When it is set, the visitor's address is read from CF-Connecting-IP.
client_ip_header—Header into which the edge writes the visitor's address: CF-Connecting-IP behind the Cloudflare tunnel, X-Forwarded-For behind your own reverse proxy. The per-client sign-in rate limit uses it. Empty means the connection's own address, or CF-Connecting-IP when access_jwt_aud is set.

felis setup and the panel's access method change write these keys. felis domain set moves hostnames that follow the default names and keeps hostnames set by hand.

[smtp] ​

KeyDefaultDescription
host—Relay host. Without a relay, no sign-in code is mailed and sign-in works by passkey only.
port587587 uses STARTTLS; 465 uses implicit TLS.
from—Sender address. Required when host is set.
username—Authentication user. Empty means the relay needs no authentication.
password_refFELIS_SMTP_PASSWORD, as written by felis setupEnvironment variable that holds the relay password. The password is kept in /etc/felis/smtp-password and the felis-smtp Secret.
max_per_hour120Install-wide cap on the mail the API sends per hour. Keep it at or below the relay's own limit.
require_tlsOn, except for a relay on this hostRefuse a relay on a port other than 465 that does not offer STARTTLS.

A relay saved on Platform settings → Notifications and retention → Mail delivery takes precedence over [smtp]. See Mail relay.

[[auth_source]] ​

Each [[auth_source]] table is a third-party Yggdrasil provider. Mojang is built in and always checked first; the tables follow in the order written. A fresh install lists LittleSkin.

KeyDescription
tagPermanent namespace of the provider's player UUIDs. Must be unique, must not contain : and must not be mojang. Changing it, even its case, gives every player of the provider a new UUID.
prefix1–4 letters or digits, unique regardless of case. Added to a player's name when that name belongs to a Mojang account, as in LS_steve.
urlFull hasJoined URL. https:// is required, except http:// for localhost or a loopback or private IP address. No query string or fragment.
api_urlOptional API root, for a provider whose hasJoined path is nonstandard; used for name and UUID lookups.
toml
[[auth_source]]
tag = "littleskin"
prefix = "LS"
url = "https://littleskin.cn/api/yggdrasil/sessionserver/session/minecraft/hasJoined"

The panel's Platform → Authentication sources page imports this list on first use. Once the Owner saves a list there, the panel's list takes precedence. See Authentication sources.

[offsite] ​

KeyDefaultDescription
endpoint—https://host[:port] of the store, without a path. http:// only for a store on a trusted network.
bucket—Bucket name. Without it there is no off-site copy.
region—Bucket region.
prefix—Key prefix. Must not contain ...
access_key_refFELIS_OFFSITE_ACCESS_KEYEnvironment variable that holds the access key.
secret_key_refFELIS_OFFSITE_SECRET_KEYEnvironment variable that holds the secret key.
key_refFELIS_OFFSITE_KEYEnvironment variable that holds the encryption key.
db_keep30Newest database bundles kept in the bucket.

The installer writes this section from the FELIS_OFFSITE_* variables and keeps the secrets in /etc/felis/offsite.env. To change the bucket, edit the section (and offsite.env for new credentials) and rerun the installer. To turn the copy off, delete the section and rerun the installer. Maintenance & Backups → Off-site copy in the panel does the same.

[archive] ​

KeyDefaultDescription
retention90dHow long the archive of a removed world (reclaimed for idleness, released or deleted) is kept.
warn_before["3d", "1d"]How long before an idle world is reclaimed its owner is warned by mail. Worlds are reclaimed after 15 days idle when world cleanup is enabled.
max_local_bytesNo capSoft cap of the backup store, for example "50Gi". At the cap, owners' backups and scheduled restore points pause, and the reaper removes the oldest owner backups and backups that already have an off-site copy.
manual_retention30dHow long an owner's backup is kept.
manual_keep5Owner backups kept per server; the oldest go first.
manual_cooldown10mShortest interval between two owner backups of one server. Administrators are not held to it.
scheduled_every1dInterval of the restore points taken of worlds played since their last one. "0s" turns them off.
scheduled_keep7Restore points kept per server.
scheduled_retention90dHow long each restore point is kept.

The Backup and audit retention card in the panel overrides every key in this table except warn_before. See World backups and Daily restore points.

[audit] ​

KeyDefaultDescription
retention365dHow long audit rows are kept. "forever" keeps every row; the minimum is 30d. Export rows that must be kept longer with felis db audit-export.

The Backup and audit retention card in the panel overrides it. See Audit log.

[registry] ​

KeyDefaultDescription
user_uploads_context/var/lib/felis/uploadsWhere uploaded build contexts are stored: /var/lib/felis/uploads on the local disk, or s3://<bucket>[/<prefix>]. The installer writes the local disk when no upload store is configured; the upload storage screen of felis setup (s on its summary) or the panel's Upload storage card changes it.
user_uploads_max_bytes4GiTotal size of all users' uploaded contexts. Each user also has a budget of 2 GiB.
context_max_bytes1GiMaximum size of one uploaded build context.
max_concurrent_builds2Builds that run at once, 1–6. Later builds queue.
build_cpu_limit2CPU limit of each build container.
build_mem_limit4GiMemory limit of each build container.
build_disk_limit12GiEphemeral storage of a build pod.
build_user_namespacesautoRun build pods in a user namespace: auto turns it on when felis-api finds at startup that the node supports it, on always, off never.
build_runtime_class—RuntimeClass for build pods, such as gVisor or Kata. Empty uses the node's default runtime.
scan_fail_on["CRITICAL"]Severities that block a built image: CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN.
scan_fail_unfixedfalseAlso block on vulnerabilities that have no fixed release.
scan_accept—Vulnerability ids and secret rule ids accepted as known risks. They are still listed in the scan and never block.
kaniko_image, trivy_imageThe copies in the in-cluster registryBuild and scan tool images. Set them only to run another build of the tools.
trivy_db_repository<registry>/mirror/trivy-db:2Repository of the vulnerability database.
trivy_java_db_repository<registry>/mirror/trivy-java-db:1Repository of the Java database.

See Upload storage and Build pipeline and submissions.

[registry.s3] ​

Used when user_uploads_context is an s3:// location.

KeyDefaultDescription
endpoint—Endpoint of the S3-compatible store.
region—Region of the store.
access_key_refFELIS_UPLOADS_S3_ACCESS_KEY, as written by the upload storage screenEnvironment variable that holds the access key.
secret_key_refFELIS_UPLOADS_S3_SECRET_KEY, as written by the upload storage screenEnvironment variable that holds the secret key.

The keys themselves are kept in /etc/felis/uploads-s3-access-key, /etc/felis/uploads-s3-secret-key and the felis-uploads-s3 Secret.

Installer-owned keys ​

The installer sets these keys on every run. Change them through the installer variable or command named here.

SectionKeyValue
[server]listen0.0.0.0:8080.
[server]root_domainThe root domain. Change it with felis domain set.
[database]urlConnection URL, including the database password. Change the password with felis rotate-token db.
[database]deploymentfelis/felis-postgres, in the host copy only: felis db runs the PostgreSQL tools inside that pod.
[k8s]namespaceminecraft, the namespace of the game servers.
[velocity]login_image, lobby_imageImages of the login space and the lobby (FELIS_LIMBO_IMAGE, FELIS_LOBBY_IMAGE). An empty lobby_image means the platform has no lobby.
[velocity]lobby_enabledfalse when the lobby was left off at install time (FELIS_WITH_LOBBY=0): felis setup creates a missing lobby stopped, and the default player entry policy leaves the lobby disabled until saved in the panel. Omitted or true starts lobby.
[velocity]login_memoryMemory of the login space as a Kubernetes quantity; empty means 512Mi. The small-host profile writes 320Mi.
[velocity]game_portFELIS_GAME_PORT.
[velocity]game_versionThe Minecraft Java Edition version the login space and lobby images were built for. The panel shows the client version players need from it, and reports it as unknown when empty.
[registry]url, build_namespaceregistry.felis.svc:5000 and felis-build.
[archive]store, local_pathtarLocal, the only supported store, and FELIS_ARCHIVE_LOCAL_PATH.

Host files ​

Files under /etc/felis ​

/etc/felis is readable by root only. Every database bundle contains a copy of the files in it, except bootstrap.done.

FileContentsWritten bySecret
felis.host.tomlHost copy of the configuration. Edit the carried sections here.InstallerContains the database password
felis.tomlLink to felis.host.toml; the default -config of every command.Installer—
felis.pod.tomlPod copy of the configuration, stored in the felis-config Secret. Regenerated on every run.InstallerContains the database password
secrets.envGenerated credentials: the database password, the internal API tokens of the game proxy, the login space, builds and operations, the Velocity forwarding secret and the registry write tokens. Reused by every rerun.Installer, felis rotate-tokenYes
offsite.envOff-site bucket credentials and encryption key, mode 0600.Installer, panelYes
smtp-passwordMail relay password.felis setupYes
uploads-s3-access-key, uploads-s3-secret-keyUpload bucket credentials.felis setup, panelYes
watchdog-heartbeat-urlHeartbeat URL, mode 0600.InstallerYes: the path is the check's key
host-settings.envInstaller settings saved in the panel: FELIS_DB_BACKUP_TIME, FELIS_DB_BACKUP_KEEP, FELIS_VELOCITY_XMX.Panel—
install.envInstall parameters later installer runs and updates reuse: FELIS_VERSION_BOOTSTRAP, FELIS_GAME_PORT, FELIS_PANEL_NODEPORT, FELIS_WORLDS_HOST_PATH. Mode 0600.Installer—
host-profileThe host profile (small or standard), kept by later installer runs.Installer—
with-lobbyWhether the lobby was enabled at install time (0 or 1), kept by later installer runs.Installer—
panel-tls.crt, panel-tls.keyTLS certificate and key of the panel. The installer issues a self-signed pair valid for 825 days.Installer, felis domain setThe key
cloudflared.ymlCloudflare tunnel configuration.Cloudflare step of felis setup, panel—
ha.envController high availability settings, kept for later installer runs and updates.Installer—
ha-vrrp-passVRRP password of the floating address.InstallerYes
node-peersPeer list last installed by felis node firewall.felis node firewall—
node-firewall.sh, control-firewall.shHost isolation firewall scripts.felis node firewall—
archive-transfer.keyKey of the archive transfers between nodes in distributed mode.InstallerYes
bootstrap.doneMarks a completed install.Installer—
system-server-images, velocity.fingerprint, previous-felis-imageInstaller records: the login space and lobby builds, what the game proxy was last started from, and the previous control-plane image for a rollback.Installer—

DANGER

Files marked as secret, and every database bundle, give full control of the install. Never copy them to an untrusted place, and never paste their contents into a support request; felis support-bundle removes their values for you.

An uninstall keeps /etc/felis unless --purge is given; see Uninstalling.

Other host paths ​

PathContents
/run/felis/watchdog-quiet-untilUnix time until which the watchdog sends no mail and no failure ping. The installer writes it while it restarts services on purpose, and the panel writes it when alerts are held. See Holding alert mail.
/var/lib/felis/watchdog/state.jsonWatchdog state between runs. Root only; it caches the relay password.
/var/lib/felis/db-backupsDatabase bundles (FELIS_DB_BACKUP_DIR).
/var/lib/felis/postgresThe database cluster of felis-postgres.
/var/lib/felis/offsite/status.jsonResult of the last off-site copy, read by felis offsite status and the watchdog.
/var/lib/felis/offsite/host-idThis host's id as a writer of the bucket. No bundle contains it.
/var/lib/felis/restore-hostThe bundle and progress record of felis restore-host.
/var/lib/felis/supportSupport bundles.
/var/lib/felis/node-controlRecords of host tasks and node operations started from the panel.
/opt/felis/velocity/plugins/felis-link/felis-link.propertiesSettings of the game proxy's Felis plugin, including its internal API token. Secret.
/opt/felis/velocity/forwarding.secretThe game proxy's forwarding secret. Secret.
/etc/rancher/k3s/k3s.yamlThe k3s administrator kubeconfig, readable by root only. Use sudo k3s kubectl.

Panel settings and precedence ​

The Owner can change several host settings in the panel. These rules decide which value applies.

Panel values over host files ​

A setting saved in the panel takes precedence over the same setting in felis.toml or a host file. Every process that uses the setting reads the panel's value from the database. Removing the panel's value makes the host value apply again.

SettingPanel locationOverridesBack to the host value
Mail relayPlatform settings → Notifications and retention → Mail delivery[smtp]Revert to install-time settings
HeartbeatPlatform settings → Notifications and retention → Monitoring heartbeat/etc/felis/watchdog-heartbeat-urlRemove heartbeat URL
Backup and audit retentionPlatform settings → Notifications and retention → Backup and audit retention[archive] retention, max_local_bytes, manual_*, scheduled_*; [audit] retentionRestore install-time settings
Authentication sourcesPlatform → Authentication sources[[auth_source]]—
  • The mail relay applies at once, without a restart, to felis-api, the watchdog, the reaper's notices and the break-glass console's codes.
  • Retention applies at once in felis-api, and in the backup Jobs and the reaper at their next run.
  • The heartbeat applies at the next watchdog run.
  • Authentication sources apply at the next game login and name lookup, without a restart.

Installer settings saved in the panel ​

Some settings belong to the installer but can be changed in the panel. The panel keeps them in /etc/felis/host-settings.env and applies them by running the installer for the affected units only.

SettingPanel locationInstaller variable
Daily backup timeMaintenance & Backups → Backups → Daily backup scheduleFELIS_DB_BACKUP_TIME
Daily backups keptMaintenance & Backups → Backups → Daily backup scheduleFELIS_DB_BACKUP_KEEP
Game proxy heap ceilingPlatform settings → Access and security → Game proxyFELIS_VELOCITY_XMX

Each later installer run and felis update uses these values as its defaults, so the Owner's choice survives upgrades. A variable named on an installer run takes precedence for that run only, and host-settings.env is left unchanged:

bash
# host-settings.env holds FELIS_VELOCITY_XMX=2G. This run uses 3G; later runs use 2G again.
curl -fsSL https://raw.githubusercontent.com/FelisMC/Felis/main/deploy/bootstrap.sh \
  | sudo FELIS_VELOCITY_XMX=3G bash

WARNING

Saving the daily backup schedule takes one backup at once. Changing the proxy heap, in the panel or through an installer run, restarts the game proxy and disconnects every player.

Changes the panel writes to host files ​

The panel's host operations write the same files as the command line, so the most recent change applies, whichever made it:

  • the access method ([auth], cloudflared.yml), as the connection step of felis setup;
  • upload storage ([registry], [registry.s3] and the upload bucket key files), as the upload storage screen of felis setup;
  • the root domain, through felis domain set;
  • the off-site copy ([offsite] and offsite.env), the same as an installer run with FELIS_OFFSITE_*;
  • credential rotation, through felis rotate-token.

Some settings exist only in the panel and have no file or variable: the player entry policy, the startup and wake policy, failover, and the maintenance window that felis update --apply checks. See Platform settings and Maintenance window.

Order of precedence ​

For the settings in Panel values over host files, from highest to lowest:

  1. The value saved in the panel.
  2. The value in felis.toml or the host file.
  3. The built-in default.

For the installer settings saved in the panel, from highest to lowest:

  1. A variable named on the current installer run.
  2. The value saved in the panel, kept in /etc/felis/host-settings.env.
  3. The installer's default.