empayre/fleet
14
0
Fork 0
mirror of https://github.com/empayre/fleet.git synced 2024-11-06 08:55:24 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Website: Improve support for indented content in Markdown lists, update MDM macOS setup docs page. (#14124)

Browse Source 
Closes: #12836 

Changes:
- Updated the `build-static-content` script to not add HTML comments to
Markdown codeblocks, and to not replace HTML comments in generated HTML
pages
- Updated the custom codeblock renderer in the `to-html` helper to add
syntax highlighting classes to Markdown codeblocks.
- Updated the indentation of content in lists on the MDM macOS setup
docs page.

---------

Co-authored-by: Rachael Shaw <r@rachael.wtf>
Co-authored-by: Mike McNeil <mikermcneil@users.noreply.github.com>
This commit is contained in:
Eric 2023-09-29 13:13:03 -07:00 committed by GitHub
parent e1333c113f
commit 9891861e58
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 127 additions and 144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

228
docs/Using Fleet/MDM-macOS-setup.md
View File

@ -32,24 +32,24 @@ Fleet UI:
2. Under **End user authentication**, enter your IdP credentials and select **Save**.
> If you've already configured [single sign-on (SSO) for logging in to Fleet](https://fleetdm.com/docs/configuration/fleet-server-configuration#okta-idp-configuration), you'll need to create a separate app in your IdP so your end users can't log in to Fleet. In this separate app, use "https://fleetserver.com/api/v1/fleet/mdm/sso/callback" for the SSO URL.
> If you've already configured [single sign-on (SSO) for logging in to Fleet](https://fleetdm.com/docs/configuration/fleet-server-configuration#okta-idp-configuration), you'll need to create a separate app in your IdP so your end users can't log in to Fleet. In this separate app, use "https://fleetserver.com/api/v1/fleet/mdm/sso/callback" for the SSO URL.
fleetctl CLI:
1. Create `fleet-config.yaml` file or add to your existing `config` YAML file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
end_user_authentication:
identity_provider_name: "Okta"
entity_id: "https://fleetserver.com"
issuer_url: "https://okta-instance.okta.com/84598y345hjdsshsfg/sso/saml/metadata"
metadata_url: "https://okta-instance.okta.com/84598y345hjdsshsfg/sso/saml/metadata"
...
```
```yaml
apiVersion: v1
kind: config
spec:
mdm:
end_user_authentication:
identity_provider_name: "Okta"
entity_id: "https://fleetserver.com"
issuer_url: "https://okta-instance.okta.com/84598y345hjdsshsfg/sso/saml/metadata"
metadata_url: "https://okta-instance.okta.com/84598y345hjdsshsfg/sso/saml/metadata"
...
```
2. Fill in the relevant information from your IdP under the `mdm.end_user_authentication` key.
@ -63,7 +63,7 @@ spec:
2. Under **End user license agreement (EULA)**, select **Upload** and choose your EULA.
> Uploading a EULA is optional. If you don't upload a EULA, the end user will skip this step and continue to the next step of the new Mac setup experience after they authenticate with your IdP.
> Uploading a EULA is optional. If you don't upload a EULA, the end user will skip this step and continue to the next step of the new Mac setup experience after they authenticate with your IdP.
### Step 3: enable end user authentication
@ -85,33 +85,33 @@ fleetctl CLI:
2. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
enable_end_user_authentication: true
...
```
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
enable_end_user_authentication: true
...
```
Learn more about team configurations options [here](./configuration-files/README.md#teams).
Learn more about team configurations options [here](./configuration-files/README.md#teams).
If you want to enable authentication on hosts that automatically enroll to "No team," we'll need to create an `fleet-config.yaml` file:
If you want to enable authentication on hosts that automatically enroll to "No team," we'll need to create an `fleet-config.yaml` file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
enable_end_user_authentication: true
...
```
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
enable_end_user_authentication: true
...
```
Learn more about "No team" configuration options [here](./configuration-files/README.md#organization-settings).
Learn more about "No team" configuration options [here](./configuration-files/README.md#organization-settings).
3. Add an `mdm.macos_setup.enable_end_user_authentication` key to your YAML document. This key accepts a boolean value.
@ -119,9 +119,9 @@ Learn more about "No team" configuration options [here](./configuration-files/RE
5. Confirm that end user authentication is enabled by running the `fleetctl get teams --name=Workstations --yaml` command.
If you enabled authentication on "No team," run `fleetctl get config`.
If you enabled authentication on "No team," run `fleetctl get config`.
You should see a `true` value for `mdm.macos_setup.enable_end_user_authentication`.
You should see a `true` value for `mdm.macos_setup.enable_end_user_authentication`.
## Bootstrap package
@ -156,20 +156,20 @@ Apple requires that your package is a distribution package. Verify that the pack
1. Run the following commands to expand you package and look at the files in the expanded folder:
```bash
$ pkgutil --expand package.pkg expanded-package
$ ls expanded-package
```
```bash
$ pkgutil --expand package.pkg expanded-package
$ ls expanded-package
```
If your package is a distribution package should see a `Distribution` file.
If your package is a distribution package should see a `Distribution` file.
2. If you don't see a `Distribution` file, run the following command to convert your package into a distribution package.
```bash
$ productbuild --package package.pkg distrbution-package.pkg
```
```bash
$ productbuild --package package.pkg distrbution-package.pkg
```
Make sure your package is a `.pkg` file.
Make sure your package is a `.pkg` file.
### Step 2: sign the package
@ -178,25 +178,25 @@ To sign the package we need a valid Developer ID Installer certificate:
1. Login to your [Apple Developer account](https://developer.apple.com/account).
2. Follow Apple's instructions to create a Developer ID Installer certificate [here](https://developer.apple.com/help/account/create-certificates/create-developer-id-certificates).
> During step 3 in Apple's instructions, make sure you choose "Developer ID Installer." You'll need this kind of certificate to sign the package.
> During step 3 in Apple's instructions, make sure you choose "Developer ID Installer." You'll need this kind of certificate to sign the package.
Confirm that certificate is installed on your Mac by opening the **Keychain Access** application. You should see your certificate in the **Certificates** tab.
Confirm that certificate is installed on your Mac by opening the **Keychain Access** application. You should see your certificate in the **Certificates** tab.
3. Run the following command in the **Terminal** application to sign your package with your Developer ID certificate:
```bash
$ productsign --sign "Developer ID Installer: Your name (Serial number)" /path/to/package.pkg /path/to/signed-package.pkg
```
```bash
$ productsign --sign "Developer ID Installer: Your name (Serial number)" /path/to/package.pkg /path/to/signed-package.pkg
```
You might be prompted to enter the password for your local account.
You might be prompted to enter the password for your local account.
Confirm that your package is signed by running the following command:
Confirm that your package is signed by running the following command:
```bash
$ pkgutil --check-signature /path/to/signed-package.pkg
```
```bash
$ pkgutil --check-signature /path/to/signed-package.pkg
```
In the output you should see that package has a "signed" status.
In the output you should see that package has a "signed" status.
### Step 3: upload the package to Fleet
@ -212,42 +212,42 @@ fleetctl CLI:
1. Upload the package to a storage location (ex. S3 or GitHub). During step 4, Fleet will retrieve the package from this storage location and host it for deployment.
> The URL must be accessible by the computer that uploads the package to Fleet.
> * This could be your local computer or the computer that runs your CI/CD workflow.
> The URL must be accessible by the computer that uploads the package to Fleet.
> * This could be your local computer or the computer that runs your CI/CD workflow.
2. Choose which team you want to add the bootstrap package to.
In this example, we'll add a bootstrap package to the "Workstations (canary)" team so that the package only gets installed on hosts that automatically enroll to this team.
In this example, we'll add a bootstrap package to the "Workstations (canary)" team so that the package only gets installed on hosts that automatically enroll to this team.
3. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
bootstrap_package: https://github.com/organinzation/repository/bootstrap-package.pkg
...
```
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
bootstrap_package: https://github.com/organinzation/repository/bootstrap-package.pkg
...
```
Learn more about team configurations options [here](./configuration-files/README.md#teams).
Learn more about team configurations options [here](./configuration-files/README.md#teams).
If you want to install the package on hosts that automatically enroll to "No team," we'll need to create an `fleet-config.yaml` file:
If you want to install the package on hosts that automatically enroll to "No team," we'll need to create an `fleet-config.yaml` file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
bootstrap_package: https://github.com/organinzation/repository/bootstrap-package.pkg
...
```
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
bootstrap_package: https://github.com/organinzation/repository/bootstrap-package.pkg
...
```
Learn more about "No team" configuration options [here](./configuration-files/README.md#organization-settings).
Learn more about "No team" configuration options [here](./configuration-files/README.md#organization-settings).
3. Add an `mdm.macos_setup.bootstrap_package` key to your YAML document. This key accepts the URL for the storage location of the bootstrap package.
@ -255,9 +255,9 @@ Learn more about "No team" configuration options [here](./configuration-files/RE
5. Confirm that your bootstrap package was uploaded to Fleet by running the `fleetctl get teams --name=Workstations --yaml` command.
If you uploaded the package to "No team," run `fleetctl get config`.
If you uploaded the package to "No team," run `fleetctl get config`.
You should see the URL for your bootstrap package as the value for `mdm.macos_setup.bootstrap_package`.
You should see the URL for your bootstrap package as the value for `mdm.macos_setup.bootstrap_package`.
## macOS Setup Assistant
@ -281,45 +281,45 @@ To customize the macOS Setup Assistant, we will do the following steps:
4. In your automatic enrollment profile, edit the `skip_setup_items` array so that it includes the panes you want to hide.
> You can modify properties other than `skip_setup_items`. These are documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/profile).
> You can modify properties other than `skip_setup_items`. These are documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/profile).
### Step 2: upload the profile to Fleet
1. Choose which team you want to add the automatic enrollment profile to.
In this example, let's assume you have a "Workstations" team as your [default team](./MDM-setup.md#step-6-optional-set-the-default-team-for-hosts-enrolled-via-abm) in Fleet and you want to test your profile before it's used in production.
In this example, let's assume you have a "Workstations" team as your [default team](./MDM-setup.md#step-6-optional-set-the-default-team-for-hosts-enrolled-via-abm) in Fleet and you want to test your profile before it's used in production.
To do this, we'll create a new "Workstations (canary)" team and add the automatic enrollment profile to it. Only hosts that automatically enroll to this team will see the custom macOS Setup Assistant.
To do this, we'll create a new "Workstations (canary)" team and add the automatic enrollment profile to it. Only hosts that automatically enroll to this team will see the custom macOS Setup Assistant.
2. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
macos_setup_assistant: ./path/to/automatic_enrollment_profile.json
...
```
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
macos_setup_assistant: ./path/to/automatic_enrollment_profile.json
...
```
Learn more about team configurations options [here](./configuration-files/README.md#teams).
Learn more about team configurations options [here](./configuration-files/README.md#teams).
If you want to customize the macOS Setup Assistant for hosts that automatically enroll to "No team," we'll need to create a `fleet-config.yaml` file:
If you want to customize the macOS Setup Assistant for hosts that automatically enroll to "No team," we'll need to create a `fleet-config.yaml` file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
macos_setup_assistant: ./path/to/automatic_enrollment_profile.json
...
```
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
macos_setup_assistant: ./path/to/automatic_enrollment_profile.json
...
```
Learn more about configuration options for hosts that aren't assigned to a team [here](./configuration-files/README.md#organization-settings).
Learn more about configuration options for hosts that aren't assigned to a team [here](./configuration-files/README.md#organization-settings).
3. Add an `mdm.macos_setup.macos_setup_assistant` key to your YAML document. This key accepts a path to your automatic enrollment profile.
@ -333,7 +333,7 @@ Testing requires a test Mac that is present in your Apple Business Manager (ABM)
2. In Fleet, navigate to the Hosts page and find your Mac. Make sure that the host's **MDM status** is set to "Pending."
> New Macs purchased through Apple Business Manager appear in Fleet with MDM status set to "Pending." Learn more about these hosts [here](./MDM-setup.md#pending-hosts).
> New Macs purchased through Apple Business Manager appear in Fleet with MDM status set to "Pending." Learn more about these hosts [here](./MDM-setup.md#pending-hosts).
3. Transfer this host to the "Workstations (canary)" team by selecting the checkbox to the left of the host and selecting **Transfer** at the top of the table. In the modal, choose the Workstations (canary) team and select **Transfer**.

18
website/api/helpers/strings/to-html.js vendored
View File

@ -98,12 +98,18 @@ module.exports = {
};
}
// Creating a custom codeblock renderer function to render mermaid code blocks (```mermaid```) without the added <pre> tags.
customRenderer.code = function(code) {
if(code.match(/\<!-- __LANG=\%mermaid\%__ --\>/g)) {
return '<code>'+_.escape(code)+'\n</code>';
} else {
return '<pre><code>'+_.escape(code)+'\n</code></pre>';
// Creating a custom codeblock renderer function to add syntax highlighting keywords and render mermaid code blocks (```mermaid```) without the added <pre> tags.
customRenderer.code = function(code, infostring) {
if(infostring === 'mermaid') {
return `<code class="mermaid">${_.escape(code)}</code>`;
} else if(infostring === 'js') {// Interpret `js` as `javascript`
return `<pre><code class="hljs javascript">${_.escape(code)}</code></pre>`;
} else if(infostring === 'bash' || infostring === 'sh') {// Interpret `sh` and `bash` as `bash`
return `<pre><code class="hljs bash">${_.escape(code)}</code></pre>`;
} else if(infostring !== '') {// leaving the code language as-is if the infoString is anything else.
return `<pre><code class="hljs ${_.escape(infostring)}">${_.escape(code)}</code></pre>`;
} else {// When unspecified, default to `text`
return `<pre><code class="nohighlight">${_.escape(code)}</code></pre>`;
}
};

25
website/scripts/build-static-content.js vendored
View File

@ -255,32 +255,9 @@ module.exports = {
if(mdString.match(/\{\{([^}]+)\}\}/gi)) {
throw new Error(`A Markdown file (${pageSourcePath}) contains a Vue template (${mdString.match(/\{\{([^}]+)\}\}/gi)[0]}) that will cause client-side javascript errors when converted to HTML. To resolve this error, change or remove the double curly brackets in this file.`);
}
mdString = mdString.replace(/(```)([a-zA-Z0-9\-]*)(\s*\n)/g, '$1\n' + '<!-- __LANG=%' + '$2' + '%__ -->' + '$3'); // « Based on the github-flavored markdown's language annotation, (e.g. ```js```) add a temporary marker to code blocks that can be parsed post-md-compilation when this is HTML. Note: This is an HTML comment because it is easy to over-match and "accidentally" add it underneath each code block as well (being an HTML comment ensures it doesn't show up or break anything). For more information, see https://github.com/uncletammy/doc-templater/blob/2969726b598b39aa78648c5379e4d9503b65685e/lib/compile-markdown-tree-from-remote-git-repo.js#L198-L202
mdString = mdString.replace(/(<call-to-action[\s\S]+[^>\n+])\n+(>)/g, '$1$2'); // « Removes any newlines that might exist before the closing `>` when the <call-to-action> compontent is added to markdown files.
// [?] Looking for code that used to be here related to syntax highlighting? Please see https://github.com/fleetdm/fleet/pull/14124/files -mikermcneil, 2023-09-25
let htmlString = await sails.helpers.strings.toHtml(mdString);
htmlString = (// « Add the appropriate class to the `<code>` based on the temporary "LANG" markers that were just added above
htmlString
.replace(// Interpret `js` as `javascript`
// $1 $2 $3 $4
/(<code)([^>]*)(>\s*)(\&lt;!-- __LANG=\%js\%__ --\&gt;)\s*/gm,
'$1 class="javascript"$2$3'
)
.replace(// Interpret `sh` and `bash` as `bash`
// $1 $2 $3 $4
/(<code)([^>]*)(>\s*)(\&lt;!-- __LANG=\%(bash|sh)\%__ --\&gt;)\s*/gm,
'$1 class="bash"$2$3'
)
.replace(// When unspecified, default to `text`
// $1 $2 $3 $4
/(<code)([^>]*)(>\s*)(\&lt;!-- __LANG=\%\%__ --\&gt;)\s*/gm,
'$1 class="nohighlight"$2$3'
)
.replace(// Finally, nab the rest, leaving the code language as-is.
// $1 $2 $3 $4 $5 $6
/(<code)([^>]*)(>\s*)(\&lt;!-- __LANG=\%)([^%]+)(\%__ --\&gt;)\s*/gm,
'$1 class="$5"$2$3'
)
);
// Throw an error if the compiled Markdown contains nested codeblocks (nested codeblocks meaning 3 backtick codeblocks nested inside a 4 backtick codeblock, or vice versa). Note: We're checking this after the markdown has been compiled because backticks (`) within codeblocks will be replaced with HTML entities (&#96;) and nested triple backticks can be easy to overmatch.
if(htmlString.match(/(&#96;){3,4}[\s\S]+(&#96;){3}/g)){
throw new Error('The compiled markdown has a codeblock (\`\`\`) nested inside of another codeblock (\`\`\`\`) at '+pageSourcePath+'. To resolve this error, remove the codeblock nested inside another codeblock from this file.');