Server configuration docs: APNs and ABM in the UI (#19461)
- Add redirect for error message on Fleet server startup if private key is missing: #19455 - Move the APNs and ABM environment variables to contributor docs. They will no longer be used
This commit is contained in:
Noah Talerman
@@ -680,12 +680,9 @@ Setting to true will disable the origin check.
|
||||
|
||||
##### server_private_key
|
||||
|
||||
The private key used to encrypt sensitive data in Fleet, for example, MDM certificates and keys.
|
||||
The key must be at least 32 bytes long. If the key is longer than 32 bytes, only the first 32 bytes
|
||||
will be used (the data is encrypted using AES-256, which requires a 32 byte key). This key is
|
||||
required for enabling MDM features in Fleet. If you are using the `FLEET_APPLE_APNS_*` and
|
||||
`FLEET_APPLE_SCEP_*` variables, Fleet will automatically encrypt the values of those variables using
|
||||
`FLEET_SERVER_PRIVATE_KEY` and save them in the database when you restart after updating.
|
||||
This key is required for enabling macOS MDM features in Fleet. If you are using the `FLEET_APPLE_APNS_*` and `FLEET_APPLE_SCEP_*` variables, Fleet will automatically encrypt the values of those variables using `FLEET_SERVER_PRIVATE_KEY` and save them in the database when you restart after updating.
|
||||
|
||||
The key must be at least 32 bytes long. Run `openssl rand -base64 32` in the Terminal app to generate one on macOS.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: FLEET_SERVER_PRIVATE_KEY
|
||||
@@ -2808,89 +2805,9 @@ packaging:
|
||||
|
||||
## Mobile device management (MDM)
|
||||
|
||||
> MDM features require some endpoints to be publicly accessible. For more details, see the guide, [Which API endpoints to expose to the public internet?](https://fleetdm.com/guides/what-api-endpoints-to-expose-to-the-public-internet)
|
||||
> The [`server_private_key` configuration option](#server_private_key) is required for macOS MDM features.
|
||||
|
||||
This section is a reference for the configuration required to turn on MDM features in production.
|
||||
|
||||
If you're a Fleet contributor and you'd like to turn on MDM features in a local environment, see the guided instructions [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#mdm-setup-and-testing).
|
||||
|
||||
##### mdm.apple_apns_cert_bytes
|
||||
|
||||
The content of the Apple Push Notification service (APNs) certificate. An X.509 certificate, PEM-encoded. Typically generated via `fleetctl generate mdm-apple`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_APNS_CERT_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_apns_cert_bytes: |
|
||||
-----BEGIN CERTIFICATE-----
|
||||
... PEM-encoded content ...
|
||||
-----END CERTIFICATE-----
|
||||
```
|
||||
|
||||
##### mdm.apple_apns_key_bytes
|
||||
|
||||
The content of the PEM-encoded private key for the Apple Push Notification service (APNs). Typically generated via `fleetctl generate mdm-apple`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_APNS_KEY_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_apns_key_bytes: |
|
||||
-----BEGIN RSA PRIVATE KEY-----
|
||||
... PEM-encoded content ...
|
||||
-----END RSA PRIVATE KEY-----
|
||||
```
|
||||
|
||||
##### mdm.apple_scep_cert_bytes
|
||||
|
||||
The content of the Simple Certificate Enrollment Protocol (SCEP) certificate. An X.509 certificate, PEM-encoded. Typically generated via `fleetctl generate mdm-apple`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_SCEP_CERT_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_scep_cert_bytes: |
|
||||
-----BEGIN CERTIFICATE-----
|
||||
... PEM-encoded content ...
|
||||
-----END CERTIFICATE-----
|
||||
```
|
||||
|
||||
The SCEP certificate/key pair [generated by Fleet](https://fleetdm.com/docs/using-fleet/MDM-setup#step-1-generate-the-required-files) expires every 10 years. It's recommended to never change these unless they were compromised.
|
||||
|
||||
If your certificate/key pair was compromised and you change the pair, the disk encryption keys will no longer be viewable on all macOS hosts' **Host details** page until you turn disk encryption off and back on and the keys are [reset by the end user](https://fleetdm.com/docs/using-fleet/MDM-migration-guide#how-to-turn-on-disk-encryption).
|
||||
|
||||
##### mdm.apple_scep_key_bytes
|
||||
|
||||
The content of the PEM-encoded private key for the Simple Certificate Enrollment Protocol (SCEP). Typically generated via `fleetctl generate mdm-apple`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_SCEP_KEY_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_scep_key_bytes: |
|
||||
-----BEGIN RSA PRIVATE KEY-----
|
||||
... PEM-encoded content ...
|
||||
-----END RSA PRIVATE KEY-----
|
||||
```
|
||||
|
||||
##### mdm.apple_scep_challenge
|
||||
|
||||
An alphanumeric secret for the Simple Certificate Enrollment Protocol (SCEP). Define a unique, static secret 32 characters in length and only include alphanumeric characters.
|
||||
|
||||
> SCEP is commonly applied to a number of certificate use cases. Notably, Mobile Device Management (MDM) systems like Microsoft Intune and Apple MDM use SCEP for PKI certificate enrollment.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_SCEP_CHALLENGE`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_scep_challenge: scepchallenge
|
||||
```
|
||||
> The Apple Push Notification service (APNs), SCEP, and Apple Business Manager (ABM) [configuration](https://github.com/fleetdm/fleet/fleet-v4.51.0/main/docs/Contributing/Configuration-for-contributors.md#mobile-device-management-mdm) are deprecated as of Fleet 4.51. They are maintained for backwards compatibility. Please upload your APNs certificate and ABM token in **Settings > Integrations MDM** and **Settings > Integrations > Automatic enrollment** respectively.
|
||||
|
||||
##### mdm.apple_scep_signer_validity_days
|
||||
|
||||
@@ -2916,51 +2833,6 @@ The number of days allowed to renew SCEP certificates.
|
||||
apple_scep_signer_allow_renewal_days: 30
|
||||
```
|
||||
|
||||
##### mdm.apple_bm_server_token_bytes
|
||||
|
||||
This is the content of the Apple Business Manager encrypted server token downloaded from Apple Business Manager.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_bm_server_token_bytes: |
|
||||
Content-Type: application/pkcs7-mime; name="smime.p7m"; smime-type=enveloped-data
|
||||
Content-Transfer-Encoding: base64
|
||||
... rest of content ...
|
||||
```
|
||||
|
||||
##### mdm.apple_bm_cert_bytes
|
||||
|
||||
This is the content of the Apple Business Manager certificate. The certificate is a PEM-encoded X.509 certificate that's typically generated via `fleetctl generate mdm-apple-bm`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_BM_CERT_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_bm_cert_bytes: |
|
||||
-----BEGIN CERTIFICATE-----
|
||||
... PEM-encoded content ...
|
||||
-----END CERTIFICATE-----
|
||||
```
|
||||
|
||||
##### mdm.apple_bm_key_bytes
|
||||
|
||||
This is the content of the PEM-encoded private key for the Apple Business Manager. It's typically generated via `fleetctl generate mdm-apple-bm`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_BM_KEY_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_bm_key_bytes: |
|
||||
-----BEGIN RSA PRIVATE KEY-----
|
||||
... PEM-encoded content ...
|
||||
-----END RSA PRIVATE KEY-----
|
||||
```
|
||||
|
||||
##### mdm.apple_dep_sync_periodicity
|
||||
|
||||
The duration between DEP device syncing (fetching and setting of DEP profiles). Only relevant if Apple Business Manager (ABM) is configured.
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
- [Integrations](#integrations)
|
||||
- [SMTP-settings](#smtp-settings)
|
||||
- [Mobile device management (MDM)](#mobile-device-management-mdm)
|
||||
- [Environment variables](#environment-variables)
|
||||
|
||||
This document includes configuration files and settings that are helpful when developing or contributing to Fleet.
|
||||
@@ -362,6 +363,135 @@ Whether the SMTP server's SSL certificates should be verified. This can be turne
|
||||
verify_ssl_certs: false
|
||||
```
|
||||
|
||||
## Mobile device management (MDM)
|
||||
|
||||
This section is a reference for the configuration required to turn on MDM features in production.
|
||||
|
||||
If you're a Fleet contributor and you'd like to turn on MDM features in a local environment, see the guided instructions [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#mdm-setup-and-testing).
|
||||
|
||||
##### mdm.apple_apns_cert_bytes
|
||||
|
||||
The content of the Apple Push Notification service (APNs) certificate. An X.509 certificate, PEM-encoded. Typically generated via `fleetctl generate mdm-apple`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_APNS_CERT_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_apns_cert_bytes: |
|
||||
-----BEGIN CERTIFICATE-----
|
||||
... PEM-encoded content ...
|
||||
-----END CERTIFICATE-----
|
||||
```
|
||||
|
||||
##### mdm.apple_apns_key_bytes
|
||||
|
||||
The content of the PEM-encoded private key for the Apple Push Notification service (APNs). Typically generated via `fleetctl generate mdm-apple`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_APNS_KEY_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_apns_key_bytes: |
|
||||
-----BEGIN RSA PRIVATE KEY-----
|
||||
... PEM-encoded content ...
|
||||
-----END RSA PRIVATE KEY-----
|
||||
```
|
||||
|
||||
##### mdm.apple_scep_cert_bytes
|
||||
|
||||
The content of the Simple Certificate Enrollment Protocol (SCEP) certificate. An X.509 certificate, PEM-encoded. Typically generated via `fleetctl generate mdm-apple`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_SCEP_CERT_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_scep_cert_bytes: |
|
||||
-----BEGIN CERTIFICATE-----
|
||||
... PEM-encoded content ...
|
||||
-----END CERTIFICATE-----
|
||||
```
|
||||
|
||||
The SCEP certificate/key pair [generated by Fleet](https://fleetdm.com/docs/using-fleet/MDM-setup#step-1-generate-the-required-files) expires every 10 years. It's recommended to never change these unless they were compromised.
|
||||
|
||||
If your certificate/key pair was compromised and you change the pair, the disk encryption keys will no longer be viewable on all macOS hosts' **Host details** page until you turn disk encryption off and back on and the keys are [reset by the end user](https://fleetdm.com/docs/using-fleet/MDM-migration-guide#how-to-turn-on-disk-encryption).
|
||||
|
||||
##### mdm.apple_scep_key_bytes
|
||||
|
||||
The content of the PEM-encoded private key for the Simple Certificate Enrollment Protocol (SCEP). Typically generated via `fleetctl generate mdm-apple`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_SCEP_KEY_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_scep_key_bytes: |
|
||||
-----BEGIN RSA PRIVATE KEY-----
|
||||
... PEM-encoded content ...
|
||||
-----END RSA PRIVATE KEY-----
|
||||
```
|
||||
|
||||
##### mdm.apple_scep_challenge
|
||||
|
||||
An alphanumeric secret for the Simple Certificate Enrollment Protocol (SCEP). Define a unique, static secret 32 characters in length and only include alphanumeric characters.
|
||||
|
||||
> SCEP is commonly applied to a number of certificate use cases. Notably, Mobile Device Management (MDM) systems like Microsoft Intune and Apple MDM use SCEP for PKI certificate enrollment.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_SCEP_CHALLENGE`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_scep_challenge: scepchallenge
|
||||
```
|
||||
|
||||
##### mdm.apple_bm_server_token_bytes
|
||||
|
||||
This is the content of the Apple Business Manager encrypted server token downloaded from Apple Business Manager.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_bm_server_token_bytes: |
|
||||
Content-Type: application/pkcs7-mime; name="smime.p7m"; smime-type=enveloped-data
|
||||
Content-Transfer-Encoding: base64
|
||||
... rest of content ...
|
||||
```
|
||||
|
||||
##### mdm.apple_bm_cert_bytes
|
||||
|
||||
This is the content of the Apple Business Manager certificate. The certificate is a PEM-encoded X.509 certificate that's typically generated via `fleetctl generate mdm-apple-bm`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_BM_CERT_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_bm_cert_bytes: |
|
||||
-----BEGIN CERTIFICATE-----
|
||||
... PEM-encoded content ...
|
||||
-----END CERTIFICATE-----
|
||||
```
|
||||
|
||||
##### mdm.apple_bm_key_bytes
|
||||
|
||||
This is the content of the PEM-encoded private key for the Apple Business Manager. It's typically generated via `fleetctl generate mdm-apple-bm`.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_BM_KEY_BYTES`
|
||||
- Config file format:
|
||||
```yaml
|
||||
mdm:
|
||||
apple_bm_key_bytes: |
|
||||
-----BEGIN RSA PRIVATE KEY-----
|
||||
... PEM-encoded content ...
|
||||
-----END RSA PRIVATE KEY-----
|
||||
```
|
||||
|
||||
## Environment variables
|
||||
|
||||
### FLEET_ENABLE_POST_CLIENT_DEBUG_ERRORS
|
||||
|
||||
Vendored
+1
-1
@@ -522,7 +522,7 @@ module.exports.routes = {
|
||||
'GET /learn-more-about/setup-abm': '/docs/using-fleet/mdm-setup#apple-business-manager-abm',
|
||||
'GET /learn-more-about/renew-apns': '/docs/using-fleet/mdm-setup#renewing-apns',
|
||||
'GET /learn-more-about/renew-abm': '/docs/using-fleet/mdm-macos-setup#renewing-abm',
|
||||
|
||||
'GET /learn-more-about/fleet-server-private-key': '/docs/using-fleet/fleet-server-configuration#server-private-key',
|
||||
|
||||
// Sitemap
|
||||
// =============================================================================================================
|
||||
|
||||
Reference in New Issue
Block a user