Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add more to docs: Jamf integration, inventory export, and sharding #700

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add more to docs: Jamf integration, inventory export, and sharding #700

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 135 additions & 0 deletions docs/apps/inventory-export.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
# Export

Zentral provides a REST API to export inventory and application data.

The exported results are available in either `CSV` or `xlsx`format.



## HTTP API

The API offers two endpoints for exporting data.

To initiate the export process, follow these steps:


1. Send a `POST` request to start a background task that aggregates the data. The response will include a UUID `task_id` and `task_result_url`. Save the task_id for subsequent requests.
2. Use a `GET` request to check the export `status` and retrieve the `download_url` when the results are available.
3. Finally, use another `GET` request to download the file or obtain a signed download URL if a cloud storage backend like AWS S3 is configured.


### Authentication

To authenticate API requests, include a token in the `Authorization` HTTP header.

To obtain a token:

- Create a service account by going to Setup > Manage users as a superuser. In the "Service accounts" subsection, click the `[Create]` button and provide a name for the service account. Save the displayed token securely.
- Alternatively, you can create an API token for a normal user, although this is not recommended. Click on the user in the User list, and use the `[+]` button next to the API token field.



The `Authorization` header should be in the following format:

```
Authorization: Token the_token_string
```

### Requests

#### /api/inventory/machines/export/

* method: `POST`, `GET`

This endpoint exports machine inventory data based on a filter query aligned with the drilldown feature.

You can provide a filter query, such as:

- Default filter `?sf=mbu-t-mis-tp-pf-hm-osv`
- Drilldown filter for including only MACOS devices: `?sf=mbu-t-mis-tp-pf-hm-osv&pf=MACOS`

Supported data formats:

* `zip`, `xlsx`

#### /api/inventory/macos_apps/export/

* method: `POST`, `GET`

This endpoint initiates a task to export macOS applications data.

Supported data formats:

* `csv`, `xlsx`

## Example:

### /api/inventory/machines/export/

Export inventory data for machines using a `POST` request:

```shell
$ curl -X POST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
https://zentral.example.com/api/inventory/machines/export/?sf=mbu-t-mis-tp-pf-hm-osv&export_format=xlsx
```

Expected response:

```json
{
"task_id": "978c246a-f8fa-4a9b-b97d-30f6bf385e55",
"task_result_url": "/api/task_result/978c246a-f8fa-4a9b-b97d-30f6bf385e55/"
}
```

### /api/inventory/macos_apps/export/

Export macOS applications data using a `POST` request:

```shell
$ curl -X POST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
https://zentral.example.com/api/inventory/macos_apps/export/
```

Expected response:

```json
{
"task_id": "8d390c23-11bc-4231-bdab-7e3f513f0d19",
"task_result_url": "/api/task_result/8d390c23-11bc-4231-bdab-7e3f513f0d19/"
}
```

To check the status of the task and obtain the download_url, use the following GET request:


```shell
$ curl -X GET \
-H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/task_result/8d390c23-11bc-4231-bdab-7e3f513f0d19/"
```

Expected response:

```shell
{
"status": "SUCCESS",
"unready": false,
"download_url": "/api/task_result/8d390c23-11bc-4231-bdab-7e3f513f0d19/download/"
}
```

Finally, to download the file, use the following `GET` request with the specified download URL:

```shell
$ curl -X GET \
-H "Authorization: Token $ZTL_API_TOKEN" \
-O "machines_inventory_export.zip" \
-L "https://zentral.example.com/api/task_result/8d390c23-11bc-4231-bdab-7e3f513f0d19/download/"
```

The file download should start shortly after executing this request.
79 changes: 79 additions & 0 deletions docs/apps/jamfpro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Jamf Pro

[Jamf Pro](https://jamf.com) is a widely used management software for the Apple platform. Zentral acts as a complementary solution for Jamf setups with bidirectional communication to Jamf Pro instances using the [Jamf Pro API](https://www.jamf.com/developers/apis/jamf-pro/overview/) and Jamf Webhooks.

This Jamf integration supports connection to more than one Jamf Pro instance, allowing staging and production or multi-tenancy setups within Zentral.

Zentral does support

## Use case

Connecting Zentral to Jamf adds comprehensive reporting, metrics, and dashboard capabilities that supplement Jamf-based device management. Zentral captures the state and change events for inventory, groups, and extension attributes of Jamf Pro instances providing a unified view for in-depth analysis and monitoring of all Jamf managed devices.

In addition, the integration helps extend the capabilities of Jamf Pro by incorporating capabilities from other modules in Zentral, such as Munki, Monolith, Osquery, and Santa, and linking them closely to Jamf Pro. That's part of what makes Zentral stand out as a consolidated, high-visibility platform which controls key aspects in endpoint management along the way with detailed reports, metrics, and sending enriched events to data lake and SIEM systems.

## Zentral configuration

To activate the jamf module, you need to add a `zentral.contrib.jamf` section to the `apps` section in `base.json`.

*Note: The jamf module is ready to use and activated in the Zentral-all-in-one instances (ZAIO is a prebuilt instance to evaluate Zentral running in AWS or GCP).*

## Instance setup

Zentral supports connecting to multiple Jamf Pro instances. You can start a new instance by clicking the button. For multitennacy setups, you would align each Jamf Pro server with a dedicated `Business unit` in Zentral. The following information needs to be provided for each Jamf Pro instance:

| Type | Description | Example | Comment |
|---------------|---------------------------------------|--------------|-----------|
| Business unit | associate with existing business unit | default | optional |
| Host | host name of the server | | mandatory |
| Port | server port number | 443 | mandatory |
| Path | path of the server API | /JSSResource | mandatory |
| User | API user name | - | mandatory |
| Password | API user password | | mandatory |
| Bearer token | Bearer token authentication | activated | mandatory |

The following setup items are available per Jamf instance.

- Link to the API docs
- Setup (or remove) Webhooks automatically
- Update instance details
- Delete the instance
- Add Tag configurations


### Tag configuration

You can create tags in Zentral based on membership in Jamf Smart and Static groups in Jamf Pro. Matching pattern names are used to automatically create tags, which are then dynamically added or removed from a machine in Zentral based on which Jamf group they belong to. Zentral uses a regex to find Jamf group names. You can use a replacement pattern to generate a customized Tag name in Zentral directly with a regex match.

To set up an automatic tagging configuration, follow these steps:
1. Click "Create"
2. Select "Group" as source
3. Choose a matching regex, e.g. filter for defined prefix matching group names will be used to automatically generate tags
4. Set replacement pattern used to generate a tag name
3. (Optional) choos from an existing Taxonomy _(You can edit the Taxonomy in Inventory > Tags section)_

### Tag config examples:

| Jamf Group name | Taxonomy | Regex | Replacement | Resulting Tag (example) |
|-------------------------|--------------|----------------------|-----------------|-------------------------------|
| Workday | - | ^Workday(.*)$ | \1 | Workday |
| JamfProtect - Analytic | Security | ^JamfProtect - (.*)$ | JAMF \1 | Security: JAMF Analytic |
| Apple Silicon M1 | - | ^Apple Silicon (.*)$ | AppleSilicon-\1 | AppleSilicon-M1 |


## API permissions

Permissions needed for the Jamf contrib app. Extra permissions needed for the **machine group** and **computer extension attribute** actions are marked with a <sup>*</sup>. The webhooks permissions are only needed during setup and teardown.

|Objects|Create|Read|Update|Delete|Notes|
|---|---|---|---|---|---|
|Computer Extension Attributes|X<sup>*</sup>|X<sup>*</sup>|||Only needed if the action is configured|
|Computers||X|X<sup>*</sup>||`Update` needed only if the extension attribute action is configured|
|Mobile Devices||X||||
|Policies||X|||to enrich the webhook events
|Smart Computer Groups||X||||
|Smart Mobile Device Groups||X||||
|Static Computer Groups|X<sup>*</sup>|X|X<sup>*</sup>||`Create` and `Update` only needed if the action is configured|
|Static Mobile Device Groups||X||||
|Users|||X<sup>*</sup>||`Update` needed to update the computers. Only needed if the extension attribute action is configured.|
|Webhooks|X<sup>*</sup>|X<sup>*</sup>|X<sup>*</sup>|X<sup>*</sup>|Only needed when setting up or tearing down the webhooks from Zentral|
78 changes: 78 additions & 0 deletions docs/apps/sharding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Sharding

## Percentage based, phased rollout

Zentral offers a powerful sharding feature that enables flexible rollout strategies for configurations and Munki-based, managed software installations. Sharding, also known as percentage rollout, is a phased approach to rolling out new configurations, new products (apps), or deploying updates to existing products. This documentation provides an overview of how sharding works in Zentral and provides examples of how it can be used to effectively manage software deployments.

## Overview

Zentral's sharding feature is designed to facilitate tight controlled rollouts for configurations as well as Munki-based app installs and patching. You can manage both the initial installation of software and the incremental rollout of updates with percentage sharding based on dynamic munki manifests and custom group assignments. The sharding value can be specified based on individual packages (pkg) within the associated pkginfo on the munki_repo level or tag based sharding can be managed in the GUI, both can be integrated into GitOps workflows.

When introducing new products, it is crucial to ensure proper testing and validation before a full deployment. This is where a phased rollout approach comes in. By deploying config or software to a small percentage of users initially, it becomes possible to gather feedback and gradually increase the rollout to larger groups. This approach helps identify and mitigate any issues that may arise during the rollout, minimizing disruption to users.

For existing products, the rollout strategy depends on the nature of the update or patch being deployed. An essential configuration, critical security patches, or bug fixes may require a simultaneous rollout to all users to minimize risk. On the other hand, non-critical updates may benefit from a more gradual rollout, involving deployment to a small group of users first and gradually increasing the rollout to minimize disruptions and identify potential issues.


## Monolith Sharding
Zentral's sharding feature provides precise planning, rollout, and reporting options for software deployments using Munki. It offers two main options: sharding and tag-based sharding. These options allow administrators to define specific rollout parameters and measure success using key performance metrics. These options are available from the start of software deployment in Munki and can be assigned in the sub-manifest.

### Sharding - Understanding the Moving Parts
Zentral's sharding feature dynamically maps shard values to computers for each product. This mapping enables verification of the desired and current status of software titles per computer with a detailed view in the GUI. By providing greater control over software distribution, sharding helps reduce Munki warnings that occur when a software title is not found in the catalog on each run.



### New Products
When introducing a new product, it is recommended to include it in all catalogs. Zentral's sub-manifests offer flexibility in managing software by allowing default/managed/optional installation, uninstallation, and upgrades. Furthermore, tags can be utilized to include or exclude specific machines from the rollout scope.

Excluded tags effectively stop further processing before evaluating anything else. By tagging machines as excluded, administrators can ensure that specific machines, such as VIPs, do not receive the software during the initial stages of the rollout.

The "Default shard" value comes into play when no shards are specified at the tag level. It represents the percentage of the fleet that will receive the software. Administrators can easily increment this value to gradually increase the rollout.

For more refined rollouts, administrators can utilize "Tag shards." By using tags and assigning numerical values falling within the specified modulo range, administrators can define precise rollout percentages for machines with specific tags.

The following table provides an overview of the effect of excluding tagged machines and the precedence of different rollout options:


| Precendence | Excluded Tags | Default Shard | Tag Shards | Effect |
|-------------|---------------|---------------|------------|----------------------------------------|
| 1 | Yes | - | - | Short-circuits processing |
| 2 | No | Yes | - | Percentage of fleet receiving software |
| 3 | No | No | Yes | Percentage based on Tag assignment |


### Existing Products
For existing products, Tags are be particularly helpful as well. Tags can be used to group and categorize clients into Munki tracks/catalogs. When it comes to sharding, Tags provide fine-grained control over tagged machines, allowing administrators to exclude specific machines or apply different sharding values based on the assigned tags. The combination of a custom or fast-track schedule for specific machine groups, along with Zentral's comprehensive reporting and progress metrics, enables accurate monitoring and management of software across the entire fleet.


### Sharding and Autopkg-munki recipes

Anything that an Autopkg recipe exists for can incorporate the Zentral sharding options. This allows you to customize the sharding behavior for "existing" products. For this to work on the munki repository level, you can modify the recipe's override plist file so the value sticks on new versions for "existing" products. By adding a new key called `<key>zentral_monolith</key>`, you can specify the desired sharding behavior.

In the plist file excerpt provided below, you can see an example of how sharding is added to an Autopkg recipe override file. The `zentral_monolith` key contains a shards dictionary that defines the sharding configuration. The `default` key within the shards dictionary specifies the default number of shards to use (in the example, it's set to 2), while the `modulo` key determines the modulo value for calculating the shard number.

```xml
<key>zentral_monolith</key>
<dict>
<key>excluded_tags</key>
<array>
<string>VIPs</string>
</array>
<key>shards</key>
<dict>
<key>default</key>
<integer>2</integer>
<key>modulo</key>
<integer>5</integer>
<key>tags</key>
<dict>
<key>Testing</key>
<integer>5</integer>
</dict>
</dict>
</dict>
```


The `tags` dictionary allows administrators to assign separate shards to be applied to machines with determined tags. Additionally, the `excluded_tags` ensures that machines with one of these tags assiged will not receive the software.

To further extend, you can add additional tags to the shards dictionary according to your requirements.