sudo

package
v2.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package sudo provides support for various methods of running commands with elevated privileges.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNoSudo is returned when no supported sudo method is found.
	ErrNoSudo = errors.New("no supported sudo method found")
	// DefaultRegistry is the default sudo repository.
	DefaultRegistry = sync.OnceValue(func() *Registry {
		provider := NewRegistry()
		RegisterDefaults(provider)
		return provider
	})
)

Functions

func Doas

func Doas(cmd string) string

Doas is a DecorateFunc that will wrap the given command in a doas call.

The command runs through an explicit POSIX shell for the same reasons as in Sudo.

func Noop

func Noop(cmd string) string

Noop is a DecorateFunc that will return the given command unmodified.

func RegisterDefaults added in v2.2.0

func RegisterDefaults(provider *Registry)

RegisterDefaults registers the sudo methods rig ships with, which is what DefaultRegistry holds. Use it to build a registry of your own without having to list them, and without missing methods added in later versions.

The order matters here and is part of what this registers: a root host with sudo installed matches both RegisterUID0Noop and RegisterSudo, and it is registered first so such a host runs its commands unmodified.

The factories are appended, so one of your own that has to take precedence over them must be registered before this call, or with Registry.RegisterFirst.

func RegisterDoas

func RegisterDoas(repository *Registry)

RegisterDoas registers a doas DecorateFunc with the given repository.

func RegisterSudo

func RegisterSudo(repository *Registry)

RegisterSudo registers a sudo DecorateFunc with the given repository.

When sudoers sets requiretty, the plain probe fails and the factory falls back to TTY, if script(1) works on the host.

func RegisterUID0Noop

func RegisterUID0Noop(repository *Registry)

RegisterUID0Noop registers a noop DecorateFunc with the given repository which can be used when the user is root.

func RegisterWindowsNoop

func RegisterWindowsNoop(repository *Registry)

RegisterWindowsNoop registers a noop DecorateFunc with the given repository if the current session has effective administrator privileges. IsInRole uses CheckTokenMembership, which returns true only when the Administrators SID is present and not marked deny-only — the correct signal for an effectively elevated token. SSH sessions on Windows always provide a full elevated token for Administrators group members regardless of UAC; WinRM does too for domain accounts or when LocalAccountTokenFilterPolicy=1 is set.

func Sudo

func Sudo(cmd string) string

Sudo is a DecorateFunc that will wrap the given command in a sudo call.

The command runs through an explicit POSIX shell: sudo execs its argument directly, so compound expressions (pipes, redirections, boolean lists) need a shell to interpret them, and rig's commands are POSIX, which the target user's login shell is not guaranteed to be.

func TTY added in v2.3.0

func TTY(command string) string

TTY is a DecorateFunc for hosts whose sudoers sets requiretty, which makes sudo refuse to run without a terminal. It runs the Sudo command inside script(1) from util-linux, which gives sudo the controlling terminal that requiretty checks for.

The command itself keeps the caller's stdin, stdout and stderr: they are set aside as descriptors 3 to 5 before script starts and put back just before sudo runs, so no data passes through the terminal. Binary input, end of input and separate stderr all work as they do with Sudo. The command's exit status comes back on descriptor 6 rather than as script's own, which is 0 when script is interrupted; a command that reports no status exits 130. Descriptor 6 writes to a temporary file that the wrapper reads back through descriptor 7. The file is removed as soon as both are open, so nothing the command does to temporary files can lose the status.

A signal sent to the wrapper, as one is when a command's context ends, stops the command as it does with Sudo, but not on its own: script puts sudo in a session of its own, and sudo does not pass on the hangup it gets when script exits. The wrapper passes SIGINT, SIGTERM and SIGHUP on to script as SIGTERM, script passes that to the shell it starts, the shell to sudo and sudo to the command. To pass signals on, the wrapper and that shell run their child in the background, and a POSIX shell starts a background command with SIGINT and SIGQUIT ignored, so unlike with Sudo the command starts with both ignored. A command whose connection is lost without a signal keeps running, as it does with Sudo.

The whole wrapper runs under sh.DefaultShell, like the command does.

Types

type Factory

type Factory = plumbing.Factory[cmd.Runner, cmd.Runner]

Factory is a factory for sudo runners.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider provides a unified interface to interact with different sudo methods. It ensures that a suitable sudo runner is lazily initialized and made available for privileged command execution.

func NewSudoProvider

func NewSudoProvider(get RunnerProvider, runner cmd.Runner) *Provider

NewSudoProvider creates a new instance of Provider with the provided RunnerProvider function and runner.

func (*Provider) SudoRunner

func (p *Provider) SudoRunner() (cmd.Runner, error)

SudoRunner returns a cmd.Runner with a sudo decorator or an error if the decorator could not be initialized.

type Registry

type Registry = plumbing.Provider[cmd.Runner, cmd.Runner]

Registry is a repository for sudo runner factories.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns a new sudo repository.

type RunnerProvider

type RunnerProvider func(cmd.Runner) (cmd.Runner, error)

RunnerProvider is a function that returns a cmd.Runner with elevated privileges given a runner.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL