Documentation
¶
Overview ¶
Package dockerargs reads the parts of a devcontainer.json that Docker, rather than the devcontainer tooling, gives meaning to:
- "runArgs", which becomes the argv of the "docker run" command the tooling builds. Parse is the single place that knows where a flag's value can be written, so its callers only have to know the values they care about and never which entry of the array holds one.
- the values themselves, whose syntax is Docker's wherever they are written: a "securityOpt" entry (ParseSecurityOpt), a capability name (Capability), a boolean (IsTrue).
Index ¶
Constants ¶
const ( // SeccompProfileDefault is the runtime's own default profile — the one a container that is // given no seccomp option at all runs under. SeccompProfileDefault = "builtin" // SeccompProfileUnconfined turns syscall filtering off. SeccompProfileUnconfined = "unconfined" )
Seccomp profile names that stand for a built-in profile rather than for the path of one to load. Docker matches them exactly, so a differently cased spelling names a file.
const AllCapabilities = "ALL"
AllCapabilities is the pseudo-capability standing for every Linux capability.
const AppArmorProfileUnconfined = "unconfined"
AppArmorProfileUnconfined removes the container's AppArmor profile, as SeccompProfileUnconfined removes its seccomp one.
const NetworkHost = "host"
NetworkHost is the network mode that puts the container in the host's network namespace.
Variables ¶
var RunFlags = []Flag{}/* 107 elements not displayed */
RunFlags is every flag "docker run" registers, as of github.com/docker/cli v29.7.1+incompatible. It includes the hidden and deprecated ones, which Docker still parses.
A flag is identified by its name, never by the spelling an argv uses: "--net" is not the short form of "--network" but a flag docker/cli registers separately, while "-v" is the shorthand of "--volume" and reaches the same entry here.
Functions ¶
func Capability ¶
Capability returns name — a capability written in "capAdd" or given to "--cap-add"/"--cap-drop" — as Docker matches it: upper-cased and prefixed with "CAP_", except for AllCapabilities, which takes no prefix.
func IsTrue ¶
IsTrue reports whether value turns on the boolean flag it was written for. Docker reads it with strconv.ParseBool and refuses to start the container on anything else; decolint reads anything else as turning the flag on, since the argv is already broken and the flag was plainly asked for.
func NetworkTarget ¶
NetworkTarget returns the network a "--network" or "--net" value names. Docker takes either the network itself ("host") or a comma-separated field list in which "name" holds it ("name=host,alias=web"), the fields being a CSV record as a mount entry's are. It lower-cases a field's key and value and trims the space around them.
A field list Docker rejects for a reason of its own — an unknown field key, an address that does not parse, a field written without a key or without a value — is read here for whatever its "name" field holds rather than treated as naming nothing. The value already fails to start the container, and reading it lets a rule name the network the author asked for instead of falling silent on it, as IsTrue reads a boolean flag Docker would reject.
The result is "" for a list naming no network at all and for one the CSV reader cannot read, neither of which says what was meant. A list naming several yields the last, which is the one Docker is left holding.
Types ¶
type Arg ¶
type Arg struct {
// Flag is the flag's canonical long name, without the leading "--". Every spelling of a flag
// reduces to it, so "-v", "--volume=x" and "--volume x" all yield "volume".
Flag string
// Value is what the argv gives the flag, which for a flag that takes no value is the value it
// stands for on its own — see [Flag.NoOptDefVal].
Value string
// Index is the argv position of the entry Value was read from. That is the flag's own entry
// whenever it carries the value ("--volume=x", "-vx", a bare "--privileged"), and the following
// entry otherwise.
Index int
}
Arg is one flag occurrence in an argv.
func Parse ¶
Parse returns every flag occurrence in argv, a "docker run" command line, ordered by the argv position each value was read from. It recognizes the entry forms pflag does:
- a value written in the flag's own entry, as "--flag=value", "-fvalue" or "-f=value";
- a flag that takes no value written bare, as "--flag" or "-f";
- a flag that takes one written bare, consuming the entry that follows;
- a run of shorthands in one entry, "-itv", ending at the first one that takes a value.
An entry consumed as a value never names a flag itself.
A flag missing from RunFlags is read both ways, as taking no value and as consuming the entry that follows: the table can only be older than Docker, never newer. Reading both costs at worst a finding Docker would not have seen, where trusting one reading would drop findings silently, on exactly the configurations a newly added flag appears in. An unrecognized shorthand names no flag to report, so it yields no Arg at all — only the two readings of the entries around it.
Parse deliberately parts from Docker in two places, both of which stop Docker's parse where they appear: the "--" terminator, and the image name that ends the flags. It reads on instead. A "runArgs" holding either is already broken — it is spliced into an argv that goes on to name the image and the flags the devcontainer tooling adds itself, which the entry would displace — so reporting what the array says is more use to its author than falling silent on all of it.
type Flag ¶
type Flag struct {
// Name is the flag's canonical long name, without the leading "--".
Name string
// Shorthand is the flag's one-character short name, without the leading "-", or "" for a flag
// that has none.
Shorthand string
// Type names the kind of value the flag stores, e.g. "bool", "string" or "list".
Type string
// NoOptDefVal is the value the flag takes when written without one. A flag that requires a
// value has none, so an empty NoOptDefVal is how pflag tells the two kinds apart.
NoOptDefVal string
}
Flag describes one flag "docker run" registers. The fields mirror pflag, whose parser docker/cli uses, closely enough that Parse can reproduce its reading of an argv.
func (Flag) TakesValue ¶
TakesValue reports whether the flag has to be given a value, either in its own argv entry or by consuming the entry that follows.
type SecurityOpt ¶
type SecurityOpt struct {
// Key names the option, e.g. "seccomp" or "no-new-privileges". Docker matches it
// case-sensitively, so it is kept as written.
Key string
// Value is what the entry gives the option, which for a bare "no-new-privileges" is the "true"
// it stands for on its own.
Value string
}
SecurityOpt is one "securityOpt" entry, equivalently one value given to "--security-opt".
func ParseSecurityOpt ¶
func ParseSecurityOpt(s string) (opt SecurityOpt, ok bool)
ParseSecurityOpt reads s the way Docker splits it:
- the key and the value are separated by the first "=", or, in an entry holding none, by the first ":";
- "no-new-privileges" is the one option that may be written bare, standing for "true".
ok is false for an entry Docker rejects outright, which is any other one left without a value.
Source Files