Skip to content

Latest commit

 

History

History
387 lines (235 loc) · 21.7 KB

operations-guide.md

File metadata and controls

387 lines (235 loc) · 21.7 KB
Raw

NanoMDM Operations Guide

This is a brief overview of the various command-line switches and HTTP endpoints (including APIs) available to NanoMDM.

Enrollment IDs

First, an aside on NanoMDM enrollment IDs:

Generally speaking in Apple MDM there are two types of MDM "channels" — the device channel and user channel. The device channel has different styles of enrollment. For example a traditional MDM device enrollment which would use the UDID field or a User Enrollment (for BYOD) which use the EnrollmentID field. Then, for the user channel there's an optional UserID field. This field changes context if it's a Shared iPad enrollment.

NanoMDM tries to reduce this complexity by collapsing these various identifiers into a single "enrollment ID" which is a single string that identifies unique enrollments. This same enrollment ID is used for targeting commands and pushes to devices. In the code we "resolve" the various identifiers to their channel- and enrollment-types and then the core NanoMDM service "normalizes" the resolved IDs into enrollment IDs. The enrollment IDs look a bit like this:

Type Platform ID Normalized ID Example
Device macOS UUID 470E005B-17C1-4537-BBB3-0EBC340D432A
User macOS UUID:UUID 470E005B-17C1-4537-BBB3-0EBC340D432A:F151140B-3988-45A9-9471-E96B49F27D93
Device iOS UUID 8b3b8ba3783e9ade1dae4fbb944ab3afc0ce5b69
User Enrollment (Device) iOS UUID b318edb72b556059a013368e3150050c5f74a2c6
Shared iPad iOS UUID:ShortName 68656c6c6f776f726c6468656c6c6f776f726c64:[email protected]

Switches

-api string

  • API key for API endpoints

API authorization in NanoMDM is simply HTTP Basic authentication using "nanomdm" as the username and the API key as the password. Omitting this switch turns off all API endpoints — NanoMDM in this mode will essentially just be for handling MDM client requests. It is not compatible with also specifying -disable-mdm.

-ca string

  • path to PEM CA cert(s)

NanoMDM validates that the device identity certificate is issued from specific CAs. This switch is the path to a file of PEM-encoded CAs to validate enrollments against.

-intermediate string

  • path to PEM intermediate cert(s)

NanoMDM validates that the device identity certificate is issued from specific CAs. This switch is the path to a file of PEM-encoded intermediate certificates that can be used to build a chain of trust to the CAs to validate enrollments against.

-cert-header string

  • HTTP header containing URL-escaped TLS client certificate

By default NanoMDM tries to extract the device identity certificate from the HTTP request by decoding the "Mdm-Signature" header. See "Pass an Identity Certificate Through a Proxy" section of this documentation for details. This corresponds to the SignMessage key being set to true in the enrollment profile.

With the -cert-header switch you can specify the name of an HTTP header that is passed to NanoMDM to read the client identity certificate. This is ostensibly to support Nginx' $ssl_client_escaped_cert in a proxy_set_header directive. Though any reverse proxy setting a similar header could be used, of course. The SignMessage key in the enrollment profile should be set appropriately.

-checkin

  • enable separate HTTP endpoint for MDM check-ins

By default NanoMDM uses a single HTTP endpoint (/mdm — see below) for both commands and results and for check-ins. If this option is specified then /mdm will only be for commands and results and /checkin will only be for MDM check-ins.

-debug

  • log debug messages

Enable additional debug logging.

-storage, -storage-dsn, & -storage-options

The -storage, -storage-dsn, & -storage-options flags together configure the storage backend(s). -storage specifies the name of the backend while -storage-dsn specifies the backend data source name (e.g. the connection string). The optional -storage-options flag specifies options for the backend if it supports them. If no storage flags are supplied then it is as if you specified -storage file -storage-dsn db meaning we use the file storage backend with db as its DSN.

Note: NanoMDM versions v0.5.0 and below used the -dsn flag while later versions switched to the -storage-dsn flag.

file storage backend

  • -storage file

Configures the file storage backend. This manages enrollment and command data within plain filesystem files and directories. It has zero dependencies and should run out of the box. The -storage-dsn flag specifies the filesystem directory for the database. The file backend has no storage options.

Example: -storage file -storage-dsn /path/to/my/db

mysql storage backend

  • -storage mysql

Configures the MySQL storage backend. The -storage-dsn flag should be in the format the SQL driver expects. Be sure to create your tables with the schema.sql file that corresponds to your NanoMDM version. Also make sure you apply any schema changes for each updated version (i.e. execute the numbered schema change files). MySQL 8.0.19 or later is required.

Example: -storage mysql -storage-dsn nanomdm:nanomdm/mymdmdb

Options are specified as a comma-separated list of "key=value" pairs. The mysql backend supports these options:

  • delete=1, delete=0
    • This option turns on or off the command and response deleter. It is disabled by default. When enabled (with delete=1) command responses, queued commands, and commands themeselves will be deleted from the database after enrollments have responded to a command.

Example: -storage mysql -storage-dsn nanomdm:nanomdm/mymdmdb -storage-options delete=1

pgsql storage backend

  • -storage pgsql

Configures the PostgreSQL storage backend. The -storage-dsn flag should be in the format the SQL driver expects. Be sure to create your tables with the schema.sql file that corresponds to your NanoMDM version. Also make sure you apply any schema changes for each updated version (i.e. execute the numbered schema change files). PostgreSQL 9.5 or later is required.

Example: -storage pgsql -storage-dsn postgres://postgres:toor@localhost:5432/nanomdm

Options are specified as a comma-separated list of "key=value" pairs. The pgsql backend supports these options:

  • delete=1, delete=0
    • This option turns on or off the command and response deleter. It is disabled by default. When enabled (with delete=1) command responses, queued commands, and commands themselves will be deleted from the database after enrollments have responded to a command.

Example: -storage pgsql -storage-dsn postgres://postgres:toor@localhost/nanomdm -storage-options delete=1

multi-storage backend

You can configure multiple storage backends to be used simultaneously. Specifying multiple sets of -storage, -storage-dsn, & -storage-options flags will configure the "multi-storage" adapter. The flags must be specified in sets and are related to each other in the order they're specified: for example the first -storage flag corresponds to the first -storage-dsn flag and so forth.

Be aware that only the first storage backend will be "used" when interacting with the system, all other storage backends are called to, but any results are discarded. In other words consider them write-only. Also beware that you will have very bizaare results if you change to using multiple storage backends in the midst of existing enrollments. You will receive errors about missing database rows or data. A storage backend needs to be around when a device (or all devices) initially enroll(s). There is no "sync" or backfill system with multiple storage backends (see the migration ability if you need this).

The multi-storage backend is really only useful if you've always been using multiple storage backends or if you're doing some type of development or testing (perhaps creating a new storage backend).

For example to use both a file and mysql backend your command line might look like: -storage file -storage-dsn db -storage mysql -storage-dsn nanomdm:nanomdm/mymdmdb. You can also mix and match backends, or mutliple of the same backend. Behavior is undefined (and probably very bad) if you specify two backends of the same type with the same DSN.

-dump

  • dump MDM requests and responses to stdout

Dump MDM request bodies (i.e. complete Plist requests) to standard output for each request.

-listen string

  • HTTP listen address (default ":9000")

Specifies the listen address (interface & port number) for the server to listen on.

-disable-mdm

  • disable MDM HTTP endpoint

This switch disables MDM client capability. This effecitvely turns this running instance into "API-only" mode. It is not compatible with having an empty -api switch.

-dm

  • URL to send Declarative Management requests to

Specifies the "base" URL to send Declarative Management requests to. The full URL is constructed from this base URL appended with the type of Declarative Management "Endpoint" request such as "status" or "declaration-items". Each HTTP request includes the NanoMDM enrollment ID as the HTTP header "X-Enrollment-ID". See this blog post for more details.

Note that the URL should likely have a trailing slash. Otherwise path elements of the URL may to be cut off but by Golang's relative URL path resolver.

-migration

  • HTTP endpoint for enrollment migrations

NanoMDM supports a lossy form of MDM enrollment "migration." Essentially if a source MDM server can assemble enough of both Authenticate and TokenUpdate messages for an enrollment you can "migrate" enrollments by sending those Plist requests to the migration endpoint. Importantly this transfers the needed Push topic, token, and push magic to continue to send APNs push notifications to enrollments.

This switch turns on the migration endpoint.

-retro

  • Allow retroactive certificate-authorization association

By default NanoMDM disallows requests which did not have a certificate association setup in their Authenticate message. For new enrollments this is fine. However for enrollments that did not have a full Authenticate message (i.e. for enrollments that were migrated) they will lack such an association and be denied the ability to connect.

This switch turns on the ability for enrollments with no existing certificate association to create one, bypassing the authorization check. Note if an enrollment already has an association this will not overwrite it; only if no existing association exists.

-version

  • print version

Print version and exit.

-webhook-url string

  • URL to send requests to

NanoMDM supports a MicroMDM-compatible webhook callback option. This switch turns on the webhook and specifies the URL.

-auth-proxy-url string

  • Reverse proxy URL target for MDM-authenticated HTTP requests

Enables the authentication proxy and reverse proxies HTTP requests from the server's /authproxy/ endpoint to this URL if the client provides the device's enrollment authentication. See below for more information.

-ua-zl-dc

  • reply with zero-length DigestChallenge for UserAuthenticate

By default NanoMDM will respond to a UserAuthenticate message with an HTTP 410. This effectively declines management of that the user channel for that MDM user. Enabling this option turns on the "zero-length" Digest Challenge mode where NanoMDM replies with an empty Digest Challenge to enable management each time a client enrolls.

Note that the UserAuthenticate message is only for "directory" MDM users and not the "primary" MDM user enrollment. See also Apple's discussion of UserAthenticate for more information.

HTTP endpoints & APIs

MDM

  • Endpoint: /mdm

The primary MDM endpoint is /mdm and needs to correspond to the ServerURL key in the enrollment profile. Both command & result handling as well as check-in handling happens on this endpoint by default. Note that if the -checkin switch is turned on then this endpoint will only handle command & result requests (having assumed that you updated your enrollment profile to include a separate CheckInURL key). Note the -disable-mdm switch will turn off this endpoint.

MDM Check-in

  • Endpoint: /checkin

The MDM check-in endpoint, if enabled, needs to correspond to the CheckInURL key in the enrollment profile. By default MDM check-ins are handled by the /mdm endpoint unless this switch is turned on in which case this endpoint handles them. This endpoint is disabled unless the -checkin switch is turned on. Note the -disable-mdm switch will turn off this endpoint.

Push Cert

  • Endpoint: /v1/pushcert

The push cert API endpoint allows for uploading an APNS push certificate. It takes a concatenated PEM-encoded APNs push certificate and private key as its HTTP body. Note the private key should not be encrypted. A quick way to utilize this endpoint is to use curl. For example:

$ cat /path/to/push.pem /path/to/push.key | curl -T - -u nanomdm:nanomdm 'http://127.0.0.1:9000/v1/pushcert'
{
	"topic": "com.apple.mgmt.External.e3b8ceac-1f18-2c8e-8a63-dd17d99435d9"
}

Here the -T - switch to curl tells it to take the standard-input and use it as the body for a PUT request to /v1/pushcert. We're also using -u to specify the API key (HTTP authentication). The server responded by telling us the topic that this Push certificate corresponds to.

Push

  • Endpoint: /v1/push/

The push API endpoint sends APNs push notifications to enrollments (which ask the MDM client to connect to the MDM server). This is a simple endpoint that takes enrollment IDs on the URL path:

$ curl -u nanomdm:nanomdm 'http://127.0.0.1:9000/v1/push/99385AF6-44CB-5621-A678-A321F4D9A2C8'
{
	"status": {
		"99385AF6-44CB-5621-A678-A321F4D9A2C8": {
			"push_result": "8B16D295-AB2C-EAB9-90FF-8615C0DFBB08"
		}
	}
}

Here we successfully pushed to the client and received a push_result UUID from our push provider.

We can queue multiple pushes at the same time, too (note the separating comma in the URL):

$ curl -u nanomdm:nanomdm '[::1]:9000/v1/push/99385AF6-44CB-5621-A678-A321F4D9A2C8,E9085AF6-DCCB-5661-A678-BCE8F4D9A2C8'
{
	"status": {
		"99385AF6-44CB-5621-A678-A321F4D9A2C8": {
			"push_result": "5736F13F-E2A2-E8B9-E21C-3973BDAA4054"
		},
		"E9085AF6-DCCB-5661-A678-BCE8F4D9A2C8": {
			"push_result": "A70400AA-C5D8-DBA7-D66E-1296B36FA7F5"
		}
	}
}

Enqueue

  • Endpoint: /v1/enqueue/

The enqueue API endpoint allows sending of commands to enrollments. It takes a raw command Plist input as the HTTP body. The cmdr.py script helps generate basic MDM commands. For example:

$ ./cmdr.py -r
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Command</key>
	<dict>
		<key>RequestType</key>
		<string>ProfileList</string>
	</dict>
	<key>CommandUUID</key>
	<string>d7408b5d-f314-461f-bc5e-4ff107c03857</string>
</dict>
</plist>

(Note the -r switch here picks a random read-only MDM command)

Then, to submit a command to a NanoMDM enrollment:

$ ./cmdr.py -r | curl -T - -u nanomdm:nanomm 'http://127.0.0.1:9000/v1/enqueue/E9085AF6-DCCB-5661-A678-BCE8F4D9A2C8'
{
	"status": {
		"E9085AF6-DCCB-5661-A678-BCE8F4D9A2C8": {
			"push_result": "16C80450-B79F-E23B-F99B-0810179F244E"
		}
	},
	"command_uuid": "1ec2a267-1b32-4843-8ba0-2b06e80565c4",
	"request_type": "ProfileList"

Here we successfully queued a command to an enrollment ID (UDID) E9085AF6-DCCB-5661-A678-BCE8F4D9A2C8 with command UUID 1ec2a267-1b32-4843-8ba0-2b06e80565c4 and we successfully sent a push request.

Note here, too, we can queue a command to multiple enrollments:

$ ./cmdr.py -r | curl -T - -u nanomdm:nanomm 'http://127.0.0.1:9000/v1/enqueue/99385AF6-44CB-5621-A678-A321F4D9A2C8,E9085AF6-DCCB-5661-A678-BCE8F4D9A2C8'

	"status": {
		"99385AF6-44CB-5621-A678-A321F4D9A2C8": {
			"push_result": "4DE6E126-CC6C-37B2-7350-3AD1871C298F"
		},
		"E9085AF6-DCCB-5661-A678-BCE8F4D9A2C8": {
			"push_result": "7B9D73CD-186B-CCF4-D585-AEE9E8E4F0F3"
		}
	},
	"command_uuid": "9b7c63eb-14b4-4739-96b0-750a5c967371",
	"request_type": "ProvisioningProfileList"
}

Finally you can skip sending the push notification request by appending ?nopush=1 to the URI:

$ ./cmdr.py -r | curl -v -T - -u nanomdm:nanomdm '[::1]:9000/v1/enqueue/99385AF6-44CB-5621-A678-A321F4D9A2C8?nopush=1'
{
	"no_push": true,
	"command_uuid": "598544b5-b681-4ce2-8914-ba7f45ff5c02",
	"request_type": "CertificateList"
}

Of course the device won't check-in to retrieve this command, it will just sit in the queue until it is told to check-in using a push notification. This could be useful if you want to send a large number of commands and only want to push after the last command is sent.

Migration

  • Endpoint: /migration

The migration endpoint (as talked about above under the -migration switch) is an API endpoint that allows sending raw TokenUpdate and Authenticate messages to establish an enrollment — in particular the APNs push topic, token, and push magic. This endpoint bypasses certificate validation and certificate authentication (though still requires API HTTP authentication). In this way we enable a way to "migrate" MDM enrollments from another MDM. This is how the llorne tool of the micro2nano project works, for example.

Version

  • Endpoint: /version

Returns a JSON response with the version of the running NanoMDM server.

Authentication Proxy

  • Endpoint: /authproxy/

If the -auth-proxy-url flag is provided then URLs that begin with /authproxy/ will be reverse-proxied to the given target URL. Importantly this endpoint will authenticate the incoming request in the same way as other MDM endpoints (i.e. Check-In or Command Report and Response) — including whether we're using TLS client configuration or not (the -cert-header flag). Put together this allow you to have MDM-authenticated content retrieval.

This feature is ostensibly to support Declarative Device Management and in particular the ability for some "Asset" declarations to use "MDM" authentication for their content. For example the com.apple.asset.data declaration supports an Authentication key for configuring this ability.

As an example example if this feature is enabled and a request comes to the server as /authproxy/foo/bar and the -auth-proxy-url was set to, say, http://[::1]:9008 then NanoMDM will reverse proxy this URL to http://[::1]:9008/foo/bar. An HTP 502 Bad Gateway response is sent back to the client for any issues proxying.

Enrollment Migration (nano2nano)

The nano2nano tool extracts migration enrollment data from a given storage backend and sends it to a NanoMDM migration endpoint. In this way you can effectively migrate between database backends. For example if you started with a file backend you could migrate to a mysql backend and vice versa. Note that MDM servers must have exactly the same server URL for migrations to operate.

Note: Enrollment migration is lossy. It is not intended to bring over all data related to an enrollment — just the absolute bare minimum of data to support a migrated device being able to operate with MDM. For example previous commands & responses and even inventory data will be missing.

Note: There are some edge cases around enrollment migration. One such case is iOS unlock tokens. If the latest TokenUpdate did not contain the enroll-time unlock token for iOS then this information is probably lost in the migration. Again this feature is only meant to migrate the absolute minimum of information to allow for a device to be sent APNs push requests and have an operational command-queue.

Switches

-debug

  • log debug messages

Enable additional debug logging.

-storage, -storage-dsn, & -storage-options

See the "-storage, -storage-dsn, & -storage-options" section, above, for NanoMDM. The syntax and capabilities are the same.

-key string

  • NanoMDM API Key

The NanoMDM API key used to authenticate to the migration endpoint.

-url string

  • NanoMDM migration URL

The URL of the NanoMDM migration endpoint. For example "http://127.0.0.1:9000/migration".

-version

  • print version

Print version and exit.

Example usage

$ ./nano2nano-darwin-amd64 -storage file -storage-dsn db -url 'http://127.0.0.1:9010/migration' -key nanomdm -debug
2021/06/04 14:29:54 level=info msg=storage setup storage=file
2021/06/04 14:29:54 level=info checkin=Authenticate device_id=99385AF6-44CB-5621-A678-A321F4D9A2C8 type=Device
2021/06/04 14:29:54 level=info checkin=TokenUpdate device_id=99385AF6-44CB-5621-A678-A321F4D9A2C8 type=Device