settings

package
v0.0.0-...-8ed7438 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 10, 2026 License: GPL-3.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DeprecatedDocString = "This setting has been deprecated, and will be removed in a future release."
)

Variables

View Source 
var AvailableConfirmationPromptSettings = map[string]string{
	string(ConfirmationPromptDefaultNo):  "Default to input of 'no'",
	string(ConfirmationPromptDefaultYes): "Default to input of 'yes'",
	string(ConfirmationPromptRetry):      "Retry the input function again",
}
View Source 
var AvailableDiffToolOptions = map[string]string{
	string(DifferInternal): "Use the builtin closure diff facility; queries the Nix store database directly",
	string(DifferNix):      "Use `nix store diff-closures` to run diffs",
	string(DifferCommand):  "Use an external command or script to run diffs",
}
View Source 
var AvailableHostKeyVerificationOptions = map[string]string{
	string(HostKeyVerificationAcceptNew): "Automatically accept new keys into known_hosts",
	string(HostKeyVerificationAsk):       "Ask whether to add new keys to known_hosts",
	string(HostKeyVerificationOff):       "Turn off all host key verification",
	string(HostKeyVerificationStrict):    "Deny all keys that do not already exist in known_hosts",
}
View Source 
var AvailablePasswordInputMethods = map[string]string{
	string(PasswordInputMethodStdin): "Prompt for the password once and pass it on stdin for all invocations",
	string(PasswordInputMethodTTY):   "Allocate a TTY and always use interactive input for password",
	string(PasswordInputMethodNone):  "Fail if command requires authentication",
}
View Source 
var DefaultAliases = map[string][]string{
	"switch":                   {"apply"},
	"boot":                     {"apply", "--no-activate"},
	"test":                     {"apply", "--no-boot"},
	"build":                    {"apply", "--no-activate", "--no-boot", "--output", "./result"},
	"build-image":              {"apply", "--no-activate", "--no-boot", "--output", "./result", "--image"},
	"build-vm":                 {"apply", "--no-activate", "--no-boot", "--output", "./result", "--vm"},
	"build-vm-with-bootloader": {"apply", "--no-activate", "--no-boot", "--output", "./result", "--vm-with-bootloader"},
	"dry-build":                {"apply", "--no-activate", "--no-boot", "--dry"},
	"dry-activate":             {"apply", "--dry"},
	"eval":                     {"apply", "--eval-only"},
	"list-generations":         {"generation", "list", "--table"},
}
View Source 
var SettingsDocs = map[string]SettingsDocEntry{
	"aliases": {
		Short: "Shortcuts for long commands",
		Long:  "Defines alternative aliases for long commands to improve user ergonomics. The default list of aliases are mapped to common operations, and they can be overridden. They can also be disabled by setting `use_default_aliases = false`.",
		Example: map[string][]string{
			"genlist":  {"generation", "list"},
			"switch":   {"generation", "switch"},
			"rollback": {"generation", "rollback"},
		},
		DefaultValue: DefaultAliases,
	},
	"apply": {
		Short: "Settings for `apply` command",
	},
	"apply.imply_impure_with_tag": {
		Short: "Add --impure automatically when using --tag with flakes",
		Long:  "Automatically appends '--impure' to the 'apply' command when using '--tag' in flake-based workflows.",
	},
	"apply.specialisation": {
		Short: "Name of specialisation to use by default when activating",
		Long:  "Specifies which specialisation to use when activating a configuration with 'apply'.",
	},
	"apply.use_nom": {
		Short: "Use 'nix-output-monitor' as an alternative 'nix build' frontend",
		Long:  "Enables nix-output-monitor to show more user-friendly build progress output for the 'apply' command.",
	},
	"apply.use_git_commit_msg": {
		Short: "Use last git commit message for --tag by default",
		Long:  "When enabled, the last Git commit message will be used as the value for '--tag' automatically.",
	},
	"apply.ignore_dirty_tree": {
		Short: "Ignore dirty working tree when using Git commit message for --tag",
		Long:  "Allows 'apply' to use Git commit messages even when the working directory is dirty.",
	},
	"apply.reexec_as_root": {
		Short: "Re-execute process as root using `root_command`",
		Long: "Re-execute process as root using `root_command`. Only applies when activating or creating boot entries on a local system," +
			" or upgrading the root user's Nix channels.",
	},
	"auto_rollback": {
		Short: "Automatically rollback system on activation failure or lack of remote acknowledgement",
		Long: "Enables automatic rollback of a NixOS system profile when an activation command fails. This can be " +
			"disabled when a reboot or some other circumstance is needed for successful activation. " +
			"In the case of remote activations, this will also run the previous switch-to-configuration if an " +
			"acknowledgement from the invoking system is not received, in order to re-establish a connection " +
			"for further troubleshooting.",
		Deprecated: "Remove this field; rollback is now configured via `rollback.enable` (defaults to `true`).",
	},
	"color": {
		Short: "Enable colored output",
		Long:  "Turns on ANSI color sequences for decorated output in supported terminals.",
	},
	"config_location": {
		Short: "Where to look for configuration by default",
		Long:  "Path to a Nix file or directory to look for user configuration in by default.",
	},
	"confirmation": {
		Short: "Settings for confirmation prompts throughout the program",
	},
	"confirmation.always": {
		Short: "Disable interactive confirmation input entirely",
		Long:  "Disables prompts that ask for user confirmation; useful for automation.",
	},
	"confirmation.empty": {
		Short: "Control confirmation prompt behavior when no input is provided",
		Long:  "Control confirmation prompt behavior when no input is provided. " + confirmationInputPossibleValues,
	},
	"confirmation.invalid": {
		Short: "Control confirmation prompt behavior when invalid input is provided",
		Long:  "Control confirmation prompt behavior when invalid input is provided. " + confirmationInputPossibleValues,
	},
	"differ": {
		Short: "Settings for specifying diff tool to use",
	},
	"differ.tool": {
		Short: "Tool used to diff two generations",
		Long: `The selected closure diff tool that is used. Can be one of 'internal', 'nix', or 'command'.
If 'command' is the value, then 'differ.command' MUST be specified. 'differ.command' is a list of
command arguments, and will have two arguments, the <before> and <after> closures, appended to it;
for example, a value of '["nvd", "diff"]' would expand to running 'nvd diff <before> <after>'.
If a command or function is not available at runtime, then 'nix' is the fallback tool used.`,
	},
	"differ.command": {
		Short: "Command used to run the diff tool",
		Long: `Shell command that is used to run the diff tool if 'command' is used.
It must take two positional arguments, appended to the command string at runtime:
the before and after closure paths.`,
	},
	"differ.query_derivations": {
		Short: "Query derivations for more accurate version strings",
		Long: `When using the internal differ, query store path derivations for more accurate version strings when they exist on the system.
This requires the 'nix-command' experimental feature to be enabled in the Nix configuration.`,
	},
	"enter": {
		Short: "Settings for `enter` command",
	},
	"enter.mount_resolv_conf": {
		Short: "Bind-mount host 'resolv.conf' inside chroot for internet access",
		Long:  "Ensures internet access by mounting the host's /etc/resolv.conf into the chroot environment.",
	},
	"init": {
		Short: "Settings for `init` command",
	},
	"init.extra_attrs": {
		Short: "Extra attributes to add to the generated configuration",
		Long:  "Extra attributes to add to the generated configuration.nix file. Usually configured indirectly through the NixOS module.",
	},
	"init.extra_config": {
		Short: "Extra Nix code to add to the generated configuration",
		Long:  "Extra Nix code to add to the generated configuration.nix verbatim. Usually configured indirectly through the NixOS module.",
	},
	"init.xserver_enabled": {
		Short: "Generate options to enable X11 display server",
		Long:  "Controls whether X11-related services and packages are configured by default during init.",
	},
	"init.desktop_config": {
		Short: "Config options for desktop environment",
		Long:  "Specifies the desktop environment configuration to inject during initialization.",
	},
	"no_confirm": {
		Short:      "Disable interactive confirmation input",
		Long:       "Disables prompts that ask for user confirmation; useful for scripts and other automation.",
		Deprecated: "Set `confirmation.always` to `true` instead.",
	},
	"option": {
		Short: "Settings for `option` command",
	},
	"option.min_score": {
		Short: "Minimum distance score to consider an option a match",
		Long:  "Sets the cutoff score for showing results in fuzzy-matched option lookups.",
	},
	"option.prettify": {
		Short: "Attempt to render options using Markdown",
		Long:  "If enabled, renders option documentation in a prettier Markdown format where applicable.",
	},
	"option.debounce_time": {
		Short: "Debounce time for searching options using the UI, in milliseconds",
		Long:  "Controls how often search results are recomputed when typing in the options UI, in milliseconds.",
	},
	"rollback": {
		Short: "Settings for automatic rollback upon failure",
	},
	"rollback.enable": {
		Short: "Automatically rollback system on activation failure or lack of remote acknowledgement",
		Long: `Enable automatic/"magic" rollback of a NixOS system profile when an activation command fails. This can be ` +
			"disabled when a reboot or some other circumstance is needed for successful activation. " +
			"In the case of remote activations, this will also run the previous switch-to-configuration if an " +
			"acknowledgement from the invoking system is not received, in order to re-establish a connection " +
			"for further troubleshooting.",
	},
	"rollback.timeout": {
		Short: "Period of time to wait for an acknowledgement from the machine invoking an activation",
		Long: "The period of time to wait for the invoking machine to send back an acknowledgement to " +
			"the destination machine after a successful activation has been performed before performing a rollback. " +
			`This only applies to remote/"magic" rollback mode for when remote activation of NixOS systems fails to be ` +
			"acknowledged. The timeout is specified as a `systemd.time(7)`-formatted time span, and must be at least 1 second.",
	},
	"ssh": {
		Short: "Settings for SSH",
	},
	"ssh.hosts_file_completion": {
		Short: "Use hosts file for SSH host completion",
		Long:  "Whether to use the hosts file (/etc/hosts) for SSH host completion.",
	},
	"ssh.host_key_verification": {
		Short: "Policy on what action to take with unknown host keys",
		Long: "What action to take when an unknown host key is encountered." +
			" By default, this will mimic OpenSSH behavior and ask interactively, if possible." +
			" If `confirmation.always` is set, then 'ask' will be overridden to 'accept-new'." +
			" If turned off, then known_hosts will not be modified and man-in-the-middle attacks" +
			" may be possible. Mostly a direct equivalent OpenSSH `StrictHostKeyChecking` setting.",
	},
	"ssh.known_hosts_files": {
		Short: "List of paths to known hosts files",
		Long:  "List of paths to known hosts files. `/etc/ssh/ssh_known_hosts` and `$HOME/.ssh/known_hosts` are always included.",
	},
	"ssh.private_key_cmd": {
		Short: "Command to run to obtain SSH private key",
		Long: "Specifies the command to run to obtain the private key for SSH connections." +
			" The command receives the host and user as the environment variables $NIXOS_CLI_SSH_HOST" +
			" and $NIXOS_CLI_SSH_USER respectively, and should output a single private key to standard output.",
		Example: map[string][]string{
			"ssh": {"sh", "-c", "rbw get $NIXOS_CLI_SSH_HOST"},
		},
	},
	"root": {
		Short: "Settings for root command escalation",
	},
	"root.command": {
		Short: "Command to use to run command as root",
		Long: "Specifies which command to use for privilege escalation (such as sudo or doas)." +
			" Password input behavior depends on the `root.password_method` setting.",
		Example: "doas",
	},
	"root.password_method": {
		Short: "Method to use for passing the invoking user's password",
		Long: "Specifies the method of password entry for the command." +
			" The `stdin` method prompts for the password once, and passes it on the process's standard input with a trailing newline for all invoking processes." +
			" The `tty` method will allocate a TTY if necessary (i.e. when running over SSH), and almost always requires interactive input." +
			" The `none` method assumes that no password is required (i.e. when a sudo user has NOPASSWD set), and will fail otherwise.",
	},
	"root_command": {
		Short:      "Command to use to promote process to root",
		Long:       "Specifies which command to use for privilege escalation (such as sudo or doas)",
		Deprecated: "Use the settings defined under the `root` key instead.",
	},
	"use_default_aliases": {
		Short: "Enables default list of aliases",
		Long:  "Enables commonly used command aliases by default; these can be overridden by configuring the `aliases` setting. Defaults are shown in the `aliases` setting.",
	},
	"use_nvd": {
		Short:      "Use 'nvd' instead of `nix store diff-closures`",
		Long:       "Use the better-looking `nvd` diffing tool when comparing configurations instead of `nix store diff-closures`.",
		Deprecated: "Set `differ.command` to `[\"nvd\", \"diff\"]` instead.",
	},
}

Functions

func CompleteConfigFlag 

func CompleteConfigFlag(_ *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

func WithConfig 

func WithConfig(ctx context.Context, cfg *Settings) context.Context

Types

type ApplySettings 

type ApplySettings struct {
	ImplyImpureWithTag    bool   `koanf:"imply_impure_with_tag"`
	DefaultSpecialisation string `koanf:"specialisation"`
	UseNom                bool   `koanf:"use_nom"`
	UseGitCommitMsg       bool   `koanf:"use_git_commit_msg"`
	IgnoreDirtyTree       bool   `koanf:"ignore_dirty_tree"`
	ReexecRoot            bool   `koanf:"reexec_as_root"`
}

type CompletionValueFunc 

type CompletionValueFunc func(key string, candidate string) ([]string, cobra.ShellCompDirective)

type ConfirmationPromptBehavior 

type ConfirmationPromptBehavior string
const (
	ConfirmationPromptRetry      ConfirmationPromptBehavior = "retry"
	ConfirmationPromptDefaultYes ConfirmationPromptBehavior = "default-yes"
	ConfirmationPromptDefaultNo  ConfirmationPromptBehavior = "default-no"
)

func (*ConfirmationPromptBehavior) UnmarshalText 

func (c *ConfirmationPromptBehavior) UnmarshalText(text []byte) error

type ConfirmationSettings 

type ConfirmationSettings struct {
	Always  bool                       `koanf:"always"`
	Invalid ConfirmationPromptBehavior `koanf:"invalid"`
	Empty   ConfirmationPromptBehavior `koanf:"empty"`
}

type DeprecatedSettingError 

type DeprecatedSettingError struct {
	Field       string
	Alternative string
}

func (DeprecatedSettingError) Error 

func (e DeprecatedSettingError) Error() string

type DiffTool 

type DiffTool string
const (
	DifferInternal DiffTool = "internal"
	DifferNix      DiffTool = "nix"
	DifferCommand  DiffTool = "command"
)

func (*DiffTool) UnmarshalText 

func (d *DiffTool) UnmarshalText(text []byte) error

type DifferSettings 

type DifferSettings struct {
	Tool             DiffTool `koanf:"tool"`
	Command          []string `koanf:"command" noset:"true"`
	QueryDerivations bool     `koanf:"query_derivations"`
}

type EnterSettings 

type EnterSettings struct {
	MountResolvConf bool `koanf:"mount_resolv_conf"`
}

type HostKeyVerificationType 

type HostKeyVerificationType string
const (
	HostKeyVerificationAcceptNew HostKeyVerificationType = "accept-new"
	HostKeyVerificationAsk       HostKeyVerificationType = "ask"
	HostKeyVerificationStrict    HostKeyVerificationType = "strict"
	HostKeyVerificationOff       HostKeyVerificationType = "off"
)

func (*HostKeyVerificationType) UnmarshalText 

func (h *HostKeyVerificationType) UnmarshalText(text []byte) error

type InitSettings 

type InitSettings struct {
	EnableXserver bool              `koanf:"xserver_enabled"`
	DesktopConfig string            `koanf:"desktop_config"`
	ExtraAttrs    map[string]string `koanf:"extra_attrs" noset:"true"`
	ExtraConfig   string            `koanf:"extra_config" noset:"true"`
}

type OptionSettings 

type OptionSettings struct {
	MinScore     int64 `koanf:"min_score"`
	Prettify     bool  `koanf:"prettify"`
	DebounceTime int64 `koanf:"debounce_time"`
}

type PasswordInputMethod 

type PasswordInputMethod string
const (
	PasswordInputMethodStdin PasswordInputMethod = "stdin"
	PasswordInputMethodTTY   PasswordInputMethod = "tty"
	PasswordInputMethodNone  PasswordInputMethod = "none"
)

func (*PasswordInputMethod) UnmarshalText 

func (p *PasswordInputMethod) UnmarshalText(text []byte) error

type RollbackSettings 

type RollbackSettings struct {
	Enable  bool                         `koanf:"enable"`
	Timeout systemdUtils.SystemdDuration `koanf:"timeout"`
}

type RootCommandSettings 

type RootCommandSettings struct {
	Command        string              `koanf:"command"`
	PasswordMethod PasswordInputMethod `koanf:"password_method"`
}

type SSHSettings 

type SSHSettings struct {
	HostsFileCompletion bool                    `koanf:"hosts_file_completion"`
	KnownHostsFiles     []string                `koanf:"known_hosts_files"`
	PrivateKeyCmd       []string                `koanf:"private_key_cmd"`
	HostKeyVerification HostKeyVerificationType `koanf:"host_key_verification"`
}

type Settings 

type Settings struct {
	Aliases           map[string][]string  `koanf:"aliases" noset:"true"`
	Apply             ApplySettings        `koanf:"apply"`
	AutoRollback      bool                 `koanf:"auto_rollback"`
	ConfigLocation    string               `koanf:"config_location"`
	Confirmation      ConfirmationSettings `koanf:"confirmation"`
	Differ            DifferSettings       `koanf:"differ"`
	Enter             EnterSettings        `koanf:"enter"`
	Init              InitSettings         `koanf:"init"`
	NoConfirm         bool                 `koanf:"no_confirm"`
	Option            OptionSettings       `koanf:"option"`
	Root              RootCommandSettings  `koanf:"root"`
	RootCommand       string               `koanf:"root_command"`
	Rollback          RollbackSettings     `koanf:"rollback"`
	SSH               SSHSettings          `koanf:"ssh"`
	UseColor          bool                 `koanf:"color"`
	UseDefaultAliases bool                 `koanf:"use_default_aliases"`
	UseNvd            bool                 `koanf:"use_nvd"`
	// contains filtered or unexported fields
}

func FromContext 

func FromContext(ctx context.Context) *Settings

func NewSettings 

func NewSettings() *Settings

func ParseSettings 

func ParseSettings(location string) (*Settings, error)

func ParseSettingsFromString 

func ParseSettingsFromString(input string) (*Settings, error)

func (*Settings) SetValue 

func (cfg *Settings) SetValue(key string, value string) error

func (*Settings) Validate 

func (cfg *Settings) Validate() SettingsErrors

Validate the configuration and remove any erroneous values. A list of detected errors is returned, if any exist.

type SettingsDocEntry 

type SettingsDocEntry struct {
	// A short description when displaying completion
	// script prompts or other short-form docs.
	Short string

	// A long description to embed in long-form
	// documentation like the website and man pages.
	Long string

	// An example of how this value can be set.
	// This value is serialized to TOML.
	Example any

	// This field is only set when custom text is required
	// for the default value, since it isn't reflected in
	// the actual default NewSettings value.
	DefaultValue any

	// If the value is set to be removed in a future release,
	// this field describes what to do instead.
	Deprecated string
}

type SettingsError 

type SettingsError struct {
	Field   string
	Message string
}

func (SettingsError) Error 

func (e SettingsError) Error() string

type SettingsErrors 

type SettingsErrors []error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.