Documentation
¶
Overview ¶
Package mdmctl implements the admin CLI. cmd/mdmctl is a main that parses argv and calls Run; everything else lives here.
Why ¶
The split is forced by arithmetic rather than taste. scripts/coverage-gate.sh computes the repository figure from every package in the merged profile, including exempt ones, and make test runs with -coverpkg=./..., so an uncovered command package still drags the total down. The cmd/ exemption suppresses the per-package line and nothing more. Keeping the logic here means it is gated at 95% like everything else; micromdm's cmd/mdmctl is 3185 lines with three trivial tests, and nanohubctl has none.
Two behaviours are worth knowing about. Credentials are referenced, never stored: the config file holds the name of an environment variable or a file path, and there is no subcommand whose job is printing a secret. And the output modes are separate on purpose, with -output json emitting the server's bytes unchanged so canonical JSON survives to jq.
References ¶
- Decision record: docs/research/decisions/0035-mdmctl-structure-and-credentials.md
- Decision record: docs/research/decisions/0036-mdmctl-explain-over-schema-support.md
- Decision record: docs/research/decisions/0034-admin-api-and-authorization.md
- Plan of record: docs/research/implementation_plan.md (phase 8)
- E2E scenarios: docs/testing/e2e-scenarios.md (E2E-024)
Index ¶
Constants ¶
const ( ExitOK = 0 ExitFailed = 1 // the request failed: network, 5xx, malformed response ExitUsage = 2 // unknown verb, bad flag, missing argument ExitPartial = 3 // the request succeeded but some targets did not ExitAuth = 4 // 401 or 403 )
Exit codes. They are documented and distinct so a script can tell a usage mistake from a refusal from a partial success. Both reference CLIs exit 1 from arbitrary depth, which tells a caller nothing.
const DefaultServer = "http://127.0.0.1:8080"
DefaultServer is used when neither -server, MDMCTL_SERVER, nor the selected config context names one.
Variables ¶
var ( // ErrUsage is a command-line mistake rather than a server refusal. ErrUsage = errors.New("usage") // ErrPartial is a request that succeeded with some targets refused. ErrPartial = errors.New("partial success") )
Errors that select an exit code.
var ErrConfigPermissions = errors.New("mdmctl: config file is readable by other users")
ErrConfigPermissions is a config file other users can read.
Functions ¶
func DefaultConfigPath ¶
DefaultConfigPath is where the config lives when none is given.
Types ¶
type Config ¶
type Config struct {
Current string `json:"current"`
Contexts map[string]Context `json:"contexts"`
}
Config is the on-disk configuration.
A context holds a reference to a credential, never the credential. micromdm's mdmctl writes the live API token into ~/.micromdm/<name>.json under a directory it creates 0777, and its `config print` echoes the token to stdout; nanohubctl writes the key and prints it too. The file is the thing that leaks, and naming an environment variable or a file path costs the operator nothing.
type Context ¶
type Context struct {
Server string `json:"server"`
// TokenEnv names an environment variable holding the credential.
TokenEnv string `json:"token_env,omitempty"`
// TokenFile names a file holding the credential.
TokenFile string `json:"token_file,omitempty"`
// Token is an inlined credential. Writing one requires an explicit flag
// and prints a warning; it exists because some environments have nowhere
// better, not because it is a good idea.
Token string `json:"token,omitempty"`
}
Context is one server the CLI talks to.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package adminclient is the typed HTTP client mdmctl uses against the reference server's admin API.
|
Package adminclient is the typed HTTP client mdmctl uses against the reference server's admin API. |
|
Package explain answers what a command, declaration, profile payload, or status item is, and where Apple says it applies.
|
Package explain answers what a command, declaration, profile payload, or status item is, and where Apple says it applies. |