Documentation
¶
Overview ¶
Package config provides runtime path resolution for Madmail binaries.
Camouflage / Stealth Deployment ¶
In restricted network environments (e.g. Iran, Russia), server operators may need to disguise the Madmail service so that automated government scans of running processes, systemd units, and /etc/ directories do not reveal that a mail server is running.
This is achieved by renaming the binary before installation:
cp maddy /usr/local/bin/sysmond # looks like a system monitor daemon sudo ./sysmond install --simple --ip 1.2.3.4
All paths, usernames, and systemd unit names are then derived from the binary name at runtime — so they all consistently show "sysmond":
ps aux → sysmond --config /etc/sysmond/sysmond.conf run ... systemctl → sysmond.service (not madmail.service) /etc/ → /etc/sysmond/ (not /etc/maddy/) /var/lib/ → /var/lib/sysmond/ (not /var/lib/maddy/) user account → sysmond (not maddy)
Alternatively, use the --binary-name flag during install without renaming:
sudo ./maddy install --simple --ip 1.2.3.4 --binary-name sysmond
See install --help for full options.
Index ¶
- Variables
- func BinaryName() string
- func ConfigFile() string
- func DefaultConfigDir() string
- func DefaultLibexecDirPath() string
- func DefaultRuntimeDirPath() string
- func DefaultStateDirPath() string
- func EnumListMapped[V any](m *Map, name string, inheritGlobal, required bool, mapped map[string]V, ...)
- func EnumMapped[V any](m *Map, name string, inheritGlobal, required bool, mapped map[string]V, ...)
- func NodeErr(node Node, f string, args ...interface{}) error
- func ParseBool(s string) (bool, error)
- func ParseDataSize(s string) (int, error)
- func ServiceName() string
- func ServiceNameAt(suffix string) string
- func UserName() string
- type Endpoint
- type Map
- func (m *Map) AllowUnknown()
- func (m *Map) Bool(name string, inheritGlobal, defaultVal bool, store *bool)
- func (m *Map) Callback(name string, mapper func(*Map, Node) error)
- func (m *Map) Custom(name string, inheritGlobal, required bool, ...)
- func (m *Map) DataSize(name string, inheritGlobal, required bool, defaultVal int64, store *int64)
- func (m *Map) Duration(name string, inheritGlobal, required bool, defaultVal time.Duration, ...)
- func (m *Map) Enum(name string, inheritGlobal, required bool, allowed []string, defaultVal string, ...)
- func (m *Map) EnumList(name string, inheritGlobal, required bool, allowed, defaultVal []string, ...)
- func (m *Map) Float(name string, inheritGlobal, required bool, defaultVal float64, store *float64)
- func (m *Map) Int(name string, inheritGlobal, required bool, defaultVal int, store *int)
- func (m *Map) Int32(name string, inheritGlobal, required bool, defaultVal int32, store *int32)
- func (m *Map) Int64(name string, inheritGlobal, required bool, defaultVal int64, store *int64)
- func (m *Map) Process() (unknown []Node, err error)
- func (m *Map) ProcessWith(globalCfg map[string]interface{}, block Node) (unknown []Node, err error)
- func (m *Map) String(name string, inheritGlobal, required bool, defaultVal string, store *string)
- func (m *Map) StringList(name string, inheritGlobal, required bool, defaultVal []string, ...)
- func (m *Map) UInt(name string, inheritGlobal, required bool, defaultVal uint, store *uint)
- func (m *Map) UInt32(name string, inheritGlobal, required bool, defaultVal uint32, store *uint32)
- func (m *Map) UInt64(name string, inheritGlobal, required bool, defaultVal uint64, store *uint64)
- type Node
Constants ¶
This section is empty.
Variables ¶
var ( // StateDirectory contains the path to the directory that // should be used to store any data that should be // preserved between sessions. // // Value of this variable must not change after initialization // in cmd/maddy/main.go. StateDirectory string // RuntimeDirectory contains the path to the directory that // should be used to store any temporary data. // // It should be preferred over os.TempDir, which is // global and world-readable on most systems, while // RuntimeDirectory can be dedicated for maddy. // // Value of this variable must not change after initialization // in cmd/maddy/main.go. RuntimeDirectory string // LibexecDirectory contains the path to the directory // where helper binaries should be searched. // // Value of this variable must not change after initialization // in cmd/maddy/main.go. LibexecDirectory string )
var EffectiveConfigDir func() string
EffectiveConfigDir is set by the root package's init() to return the compile-time ConfigDirectory value (which may be overridden via -X linker flag). It may return an empty string meaning "use binary-name-based default".
var Version = "go-build"
Functions ¶
func BinaryName ¶ added in v0.20.0
func BinaryName() string
BinaryName returns the name of the running executable (without directory or extension). Symlinks are resolved so that "sysmond -> maddy" returns "sysmond". Falls back to "maddy" on error.
This is the foundation of the camouflage system: every derived path (config file, state dir, service name, username) is based on this value.
func ConfigFile ¶ added in v0.20.0
func ConfigFile() string
ConfigFile returns the absolute path to the main configuration file.
Examples:
binary "maddy" → /etc/maddy/maddy.conf binary "sysmond" → /etc/sysmond/sysmond.conf (camouflaged) -X ConfigDirectory=/etc/custom + binary "sysmond" → /etc/custom/sysmond.conf
func DefaultConfigDir ¶ added in v0.20.0
func DefaultConfigDir() string
DefaultConfigDir returns "/etc/<binaryname>". For a disguised binary "sysmond" this is "/etc/sysmond".
func DefaultLibexecDirPath ¶ added in v0.20.0
func DefaultLibexecDirPath() string
DefaultLibexecDirPath returns "/usr/lib/<binaryname>".
func DefaultRuntimeDirPath ¶ added in v0.20.0
func DefaultRuntimeDirPath() string
DefaultRuntimeDirPath returns "/run/<binaryname>".
func DefaultStateDirPath ¶ added in v0.20.0
func DefaultStateDirPath() string
DefaultStateDirPath returns "/var/lib/<binaryname>". For a disguised binary "sysmond" this is "/var/lib/sysmond".
func EnumListMapped ¶
func EnumListMapped[V any](m *Map, name string, inheritGlobal, required bool, mapped map[string]V, defaultVal []V, store *[]V)
EnumListMapped is similar to Map.EnumList but maps a stirng to a custom type.
func EnumMapped ¶
func EnumMapped[V any](m *Map, name string, inheritGlobal, required bool, mapped map[string]V, defaultVal V, store *V)
EnumMapped is similar to Map.Enum but maps a stirng to a custom type.
func ParseDataSize ¶
func ServiceName ¶ added in v0.20.0
func ServiceName() string
ServiceName returns the systemd service name derived from the binary name. A binary named "sysmond" produces "sysmond.service" — not "maddy.service".
func ServiceNameAt ¶ added in v0.20.0
ServiceNameAt returns a systemd instance service name variant. A binary named "sysmond" with suffix "@" produces "sysmond@.service".
Types ¶
type Endpoint ¶
type Endpoint struct {
Original, Scheme, Host, Port, Path string
}
Endpoint represents a site address. It contains the original input value, and the component parts of an address. The component parts may be updated to the correct values as setup proceeds, but the original value should never be changed.
func ParseEndpoint ¶
ParseEndpoint parses an endpoint string into a structured format with separate scheme, host, port, and path portions, as well as the original input string.
func (Endpoint) WithLocalHost ¶ added in v0.15.0
WithLocalHost returns a copy of the endpoint with the host set to 127.0.0.1. This is used for port access control: when a port is set to "local only", it should only bind to localhost so only Shadowsocks (which relays to 127.0.0.1) can reach it, not external connections.
type Map ¶
type Map struct {
// All values saved by Map during processing.
Values map[string]interface{}
// Values used by Process as default values if inheritGlobal is true.
Globals map[string]interface{}
// Config block used by Process.
Block Node
// contains filtered or unexported fields
}
Map structure implements reflection-based conversion between configuration directives and Go variables.
func (*Map) AllowUnknown ¶
func (m *Map) AllowUnknown()
AllowUnknown makes config.Map skip unknown configuration directives instead of failing.
func (*Map) Bool ¶
Bool maps presence of some configuration directive to a boolean variable. Additionally, 'name yes' and 'name no' are mapped to true and false correspondingly.
I.e. if directive 'io_debug' exists in processed configuration block or in the global configuration (if inheritGlobal is true) then Process will store true in target variable.
func (*Map) Callback ¶
Callback creates mapping that will call mapper() function for each directive with the specified name. No further processing is done.
Directives with the specified name will not be returned by Process if AllowUnknown is used.
It is intended to permit multiple independent values of directive with implementation-defined handling.
func (*Map) Custom ¶
func (m *Map) Custom(name string, inheritGlobal, required bool, defaultVal func() (interface{}, error), mapper func(*Map, Node) (interface{}, error), store interface{})
Custom maps configuration directive with the specified name to variable referenced by 'store' pointer.
If inheritGlobal is true - Map will try to use a value from globalCfg if none is set in a processed configuration block.
If required is true - Map will fail if no value is set in the configuration, both global (if inheritGlobal is true) and in the processed block.
defaultVal is a factory function that should return the default value for the variable. It will be used if no value is set in the config. It can be nil if required is true. Note that if inheritGlobal is true, defaultVal of the global directive will be used instead.
mapper is a function that should convert configuration directive arguments into variable value. Both functions may fail with errors, configuration processing will stop immediately then. Note: mapper function should not modify passed values.
store is where the value returned by mapper should be stored. Can be nil (value will be saved only in Map.Values).
func (*Map) DataSize ¶
DataSize maps configuration directive to a int variable, representing data size.
Syntax requires unit suffix to be added to the end of string to specify data unit and allows multiple arguments (they will be added together).
See Map.Custom for description of arguments.
func (*Map) Duration ¶
func (m *Map) Duration(name string, inheritGlobal, required bool, defaultVal time.Duration, store *time.Duration)
Duration maps configuration directive to a time.Duration variable.
Directive must be in form 'name duration' where duration is any string accepted by time.ParseDuration. As an additional requirement, result of time.ParseDuration must not be negative.
Note that for convenience, if directive does have multiple arguments, they will be joined without separators. E.g. 'name 1h 2m' will become 'name 1h2m' and so '1h2m' will be passed to time.ParseDuration.
See Map.Custom for description of arguments.
func (*Map) Enum ¶
func (m *Map) Enum(name string, inheritGlobal, required bool, allowed []string, defaultVal string, store *string)
Enum maps a configuration directive to a string variable.
Directive must be in form 'name string' where string should be from *allowed* slice. That string argument will be stored in store variable.
See Map.Custom for description of inheritGlobal and required.
func (*Map) EnumList ¶
func (m *Map) EnumList(name string, inheritGlobal, required bool, allowed, defaultVal []string, store *[]string)
EnumList maps a configuration directive to a []string variable.
Directive must be in form 'name string1 string2' where each string should be from *allowed* slice. At least one argument should be present.
See Map.Custom for description of inheritGlobal and required.
func (*Map) Float ¶
Float maps configuration directive with the specified name to variable referenced by 'store' pointer.
Configuration directive must be in form 'name 123.55'.
See Custom function for details about inheritGlobal, required and defaultVal.
func (*Map) Int ¶
Int maps configuration directive with the specified name to variable referenced by 'store' pointer.
Configuration directive must be in form 'name 123'.
See Custom function for details about inheritGlobal, required and defaultVal.
func (*Map) Int32 ¶
Int32 maps configuration directive with the specified name to variable referenced by 'store' pointer.
Configuration directive must be in form 'name 123'.
See Custom function for details about inheritGlobal, required and defaultVal.
func (*Map) Int64 ¶
Int64 maps configuration directive with the specified name to variable referenced by 'store' pointer.
Configuration directive must be in form 'name 123'.
See Custom function for details about inheritGlobal, required and defaultVal.
func (*Map) Process ¶
Process maps variables from global configuration and block passed in NewMap.
If Map instance was not created using NewMap - Process panics.
func (*Map) ProcessWith ¶
Process maps variables from global configuration and block passed in arguments.
func (*Map) String ¶
String maps configuration directive with the specified name to variable referenced by 'store' pointer.
Configuration directive must be in form 'name arbitrary_string'.
See Custom function for details about inheritGlobal, required and defaultVal.
func (*Map) StringList ¶
func (m *Map) StringList(name string, inheritGlobal, required bool, defaultVal []string, store *[]string)
StringList maps configuration directive with the specified name to variable referenced by 'store' pointer.
Configuration directive must be in form 'name arbitrary_string arbitrary_string ...' Where at least one argument must be present.
See Custom function for details about inheritGlobal, required and defaultVal.
func (*Map) UInt ¶
UInt maps configuration directive with the specified name to variable referenced by 'store' pointer.
Configuration directive must be in form 'name 123'.
See Custom function for details about inheritGlobal, required and defaultVal.
func (*Map) UInt32 ¶
UInt32 maps configuration directive with the specified name to variable referenced by 'store' pointer.
Configuration directive must be in form 'name 123'.
See Custom function for details about inheritGlobal, required and defaultVal.
Source Files
Directories