userslocking

Documentation

Overview

Package userslocking implements locking of the local user and group files (/etc/passwd, /etc/groups, /etc/shadow, /etc/gshadow) via the libc lckpwdf() function.

It is recommended by systemd to hold this lock when picking a new UID/GID to avoid races, even if the new user/group is not added to the local user/group files. See https://github.com/systemd/systemd/blob/main/docs/UIDS-GIDS.md.

Index

• Variables
• func WriteLock() error
• func WriteUnlock() error
• func Z_ForTests_OverrideLocking()
• func Z_ForTests_OverrideLockingAsLockedExternally(t *testing.T, ctx context.Context)
• func Z_ForTests_OverrideLockingWithCleanup(t *testing.T)
• func Z_ForTests_RestoreLocking()
• func Z_ForTests_SetMaxWaitTime(t *testing.T, maxWaitTime time.Duration)
• type SimpleMock
  • func (t *SimpleMock) WriteLock() error
  • func (t *SimpleMock) WriteUnlock() error

Variables

var (
	// ErrLock is the error when locking the database fails.
	ErrLock = errors.New("failed to lock the system's user database")

	// ErrUnlock is the error when unlocking the database fails.
	ErrUnlock = errors.New("failed to unlock the system's user database")

	// ErrLockTimeout is the error when unlocking the database fails because of timeout.
	ErrLockTimeout = fmt.Errorf("%w: timeout", ErrLock)
)

Functions

func WriteLock

func WriteLock() error

WriteLock locks for writing the the local user entries database by using the standard libc lckpwdf() function. While the database is locked read operations can happen, but no other process is allowed to write. Note that this call will block all the other processes trying to access the database in write mode, while it will return an error if called while the lock is already hold by this process.

func WriteUnlock

func WriteUnlock() error

WriteUnlock unlocks for writing the local user entries database by using the standard libc ulckpwdf() function. As soon as this function is called all the other waiting processes will be allowed to take the lock.

func Z_ForTests_OverrideLocking

func Z_ForTests_OverrideLocking()

Z_ForTests_OverrideLocking is a function to override the locking functions for testing purposes. It simulates the real behavior but without actual file locking. Use Z_ForTests_RestoreLocking once done with it.

nolint:revive,nolintlint // We want to use underscores in the function name here.

func Z_ForTests_OverrideLockingAsLockedExternally

func Z_ForTests_OverrideLockingAsLockedExternally(t *testing.T, ctx context.Context)

Z_ForTests_OverrideLockingAsLockedExternally simulates a scenario where the user database is locked by an external process.

When called, it marks the user database as locked, causing any subsequent locking attempts by authd (via WriteLock) to block until the provided context is cancelled.

This does not use real file locking. The lock can be released either by cancelling the context or by calling WriteUnlock. After the test, Z_ForTests_RestoreLocking is called automatically to restore normal behavior.

nolint:revive,nolintlint // We want to use underscores in the function name here.

func Z_ForTests_OverrideLockingWithCleanup

func Z_ForTests_OverrideLockingWithCleanup(t *testing.T)

Z_ForTests_OverrideLockingWithCleanup is a function to override the locking functions for testing purposes. It simulates the real behavior but without actual file locking. This implicitly calls Z_ForTests_RestoreLocking once the test is completed.

nolint:revive,nolintlint // We want to use underscores in the function name here.

func Z_ForTests_RestoreLocking

func Z_ForTests_RestoreLocking()

Z_ForTests_RestoreLocking restores the locking overridden done by Z_ForTests_OverrideLocking or Z_ForTests_OverrideLockingAsLockedExternally.

nolint:revive,nolintlint // We want to use underscores in the function name here.

func Z_ForTests_SetMaxWaitTime

func Z_ForTests_SetMaxWaitTime(t *testing.T, maxWaitTime time.Duration)

Z_ForTests_SetMaxWaitTime sets the max time that we should wait before returning a failure in WriteLock.

nolint:revive,nolintlint // We want to use underscores in the function name here.

Types

type SimpleMock

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

SimpleMock is a structure that can be used to simulate the users database lock without relying on the actual file locking.

func (*SimpleMock) WriteLock

func (t *SimpleMock) WriteLock() error

WriteLock locks the mock.

func (*SimpleMock) WriteUnlock

func (t *SimpleMock) WriteUnlock() error

WriteUnlock unlocks the mock.