Documentation
¶
Overview ¶
============================================================================= NFTBan v1.73 - Installer State File I/O ============================================================================= SPDX-License-Identifier: MPL-2.0 meta:name="installer-state-file" meta:type="lib" meta:owner="Antonios Voulvoulis <contact@nftban.com>" meta:created_date="2026-04-04" meta:description="State file struct, atomic write, read, transition persistence" meta:inventory.files="internal/installer/state/file.go" meta:inventory.binaries="" meta:inventory.env_vars="" meta:inventory.config_files="/var/lib/nftban/state/install_state" meta:inventory.systemd_units="" meta:inventory.network="" meta:inventory.privileges="root" =============================================================================
============================================================================= NFTBan v1.73 - Installer State Machine ============================================================================= SPDX-License-Identifier: MPL-2.0 meta:name="installer-state-machine" meta:type="lib" meta:owner="Antonios Voulvoulis <contact@nftban.com>" meta:created_date="2026-04-04" meta:description="Install state enum, phase enum, exit codes, resume logic" meta:inventory.files="internal/installer/state/machine.go" meta:inventory.binaries="" meta:inventory.env_vars="" meta:inventory.config_files="" meta:inventory.systemd_units="" meta:inventory.network="" meta:inventory.privileges="none" =============================================================================
Index ¶
Constants ¶
const ( ExitCommitted = 0 ExitDegraded = 1 ExitFailed = 2 ExitAborted = 3 ExitFatal = 4 )
ExitCode is the process exit code contract for nftban-installer.
Contract (frozen):
0 = COMMITTED — all phases passed, firewall running and verified 1 = DEGRADED — firewall running but some validation checks failed 2 = FAILED — a critical phase failed, firewall may not be running 3 = ABORTED — conflicting firewalls detected, no --takeover flag 4 = FATAL — unrecoverable error (binary not found, permission denied)
const DefaultStateDir = "/var/lib/nftban/state"
DefaultStateDir is the standard location for install state.
const StateFileName = "install_state"
StateFileName is the install state file name.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type InstallState ¶
type InstallState string
InstallState represents the current state of the installation process.
const ( StateFilesInstalled InstallState = "FILES_INSTALLED" StateDetectComplete InstallState = "DETECT_COMPLETE" StatePrepareComplete InstallState = "PREPARE_COMPLETE" StateSwitchComplete InstallState = "SWITCH_COMPLETE" StateServicesComplete InstallState = "SERVICES_COMPLETE" StateCommitted InstallState = "COMMITTED" StateDegraded InstallState = "DEGRADED" StateFailedSSH InstallState = "FAILED_SSH_UNKNOWN" StateFailedAbort InstallState = "FAILED_AUTHORITY_ABORT" StateFailedRender InstallState = "FAILED_RENDER" StateFailedRebuild InstallState = "FAILED_REBUILD" StateFailedNoFirewall InstallState = "FAILED_NO_FIREWALL" StateFailedTakeover InstallState = "FAILED_TAKEOVER" )
func (InstallState) ExitCode ¶
func (s InstallState) ExitCode() int
ExitCode returns the process exit code for this state.
func (InstallState) IsFailed ¶
func (s InstallState) IsFailed() bool
IsFailed returns true if the state represents a failure.
func (InstallState) IsTerminal ¶
func (s InstallState) IsTerminal() bool
IsTerminal returns true if the state is a final state (no further transitions).
func (InstallState) ResumePhase ¶
func (s InstallState) ResumePhase() Phase
ResumePhase returns the phase to resume from when running in --repair mode.
type StateFile ¶
type StateFile struct {
State InstallState
Mode string
Version string
Timestamp time.Time
SSHPort int
Authority string
Panel string
Conflicts string
SchemaVersion string
PhaseReached string
FailureReason string
PreflightPassed bool
RebuildExitCode int
RebuildDurationMs int64
ServicesEnabled string
ServicesFailed string
// contains filtered or unexported fields
}
StateFile holds all install state and handles persistence.
Schema contract (frozen):
INSTALL_STATE — current InstallState enum value INSTALL_MODE — "install" or "upgrade" INSTALL_VERSION — version string (e.g. "1.73.0") INSTALL_TIMESTAMP — RFC3339 UTC timestamp SSH_PORT — detected SSH port (int) AUTHORITY — "UPDATE", "TAKEOVER", "FRESH", or "" PANEL — detected panel type or "" CONFLICTS — comma-separated conflict names or "" SCHEMA_VERSION — nftables schema version (e.g. "0.7.3") PHASE_REACHED — last phase name reached FAILURE_REASON — human-readable failure description or "" PREFLIGHT_PASSED — "1" or "0" REBUILD_EXIT_CODE — rebuild process exit code (int) REBUILD_DURATION_MS — rebuild wall-clock duration in milliseconds SERVICES_ENABLED — comma-separated list of enabled service units SERVICES_FAILED — comma-separated list of failed service units
func NewStateFile ¶
NewStateFile creates a new StateFile with the given state directory. If stateDir is empty, DefaultStateDir is used.
func (*StateFile) Read ¶
Read reads an existing state file. Returns os.ErrNotExist if file is missing (which is normal for a fresh install).
func (*StateFile) Transition ¶
func (sf *StateFile) Transition(newState InstallState, phase Phase, reason string) error
Transition validates and applies a state transition. It updates the state, phase, and optional failure reason, then persists atomically. For failure states, it always returns an error (the reason) so phase runners halt.
func (*StateFile) WriteAtomic ¶
WriteAtomic writes the state file atomically (write to tmp, then rename).
Source Files