Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-05-06 06:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 117

Docs Editor Pass - Using Fleet - Adding hosts (#6165)

Browse source 
- Editor pass that includes making all text representing a button bold
This commit is contained in:
Desmi-Dizney 2022-07-05 08:13:02 -05:00 committed by GitHub
parent 700bb9aa98
commit 519bb0f855
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 27 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

51
docs/Using-Fleet/Adding-hosts.md
View file

@ -13,14 +13,14 @@ To create an osquery installer, you can use the `fleetctl package` command.
`fleetctl package` can be used to create an osquery installer which adds macOS hosts (**.pkg**), Windows hosts (**.msi**), or Linux hosts (**.deb** or **.rpm**) to Fleet.
The following command creates an osquery installer, `.pkg` file, which adds macOS hosts to Fleet. This osquery installer is located in the folder where the `fleetctl package` command is run.
The following command creates an osquery installer, `.pkg` file, which adds macOS hosts to Fleet. Locate this osquery installer in the folder where the `fleetctl package` command is run.
```sh
fleetctl package --type pkg --fleet-url=[YOUR FLEET URL] --enroll-secret=[YOUR ENROLLMENT SECRET]
```
>**Note:** The only configuration option required to create an installer is `--type`, but to communicate with a Fleet instance you'll need to specify a `--fleet-url` and `--enroll-secret`
>**Note:** The only configuration option required to create an installer is `--type`, but to communicate with a Fleet instance, you'll need to specify a `--fleet-url` and `--enroll-secret`
When you install the generated osquery installer on a host, this host will be automatically enrolled in the specified Fleet instance.
When you install the generated osquery installer on a host, this host will automatically enroll in the specified Fleet instance.
### Signing installers
@ -36,7 +36,7 @@ Check out the example below:
The above command should be run on a macOS device as notarizing and signing of macOS osquery installers can only be done on macOS devices.
Also remember to replace both `AC_USERNAME` and `AC_PASSWORD` environment variables with your Apple ID and a valid [app-specific](https://support.apple.com/en-ca/HT204397) password respectively.
Also, remember to replace both `AC_USERNAME` and `AC_PASSWORD` environment variables with your Apple ID and a valid [app-specific](https://support.apple.com/en-ca/HT204397) password, respectively.
### Fleet Desktop
@ -47,7 +47,7 @@ Also remember to replace both `AC_USERNAME` and `AC_PASSWORD` environment variab
How to install Fleet Desktop on your hosts:
1. On the top bar in the Fleet UI, select **Hosts > Add hosts**.
2. Select the **Include Fleet Desktop** checkbox.
3. Select the clipboard icon to copy the `fleetctl package` command.
3. Select the clipboard icon to copy the `fleetctl package` command.
4. In your terminal application, paste and run the copied command.
When you install the generated osquery installer on a host, Fleet Desktop will be installed on this
@ -73,23 +73,23 @@ You can distribute your osquery installer and add all your hosts to Fleet using
`Applies only to Fleet Premium`
```
ℹ️ In Fleet 4.0, Teams were introduced.
ℹ️ Fleet 4.0 introduced Teams.
```
The teams feature in Fleet allows you to place hosts in exclusive groups. With hosts segmented into teams, you can apply unique queries and give users access to only the hosts in specific teams.
The Teams feature in Fleet allows you to place hosts in exclusive groups. With hosts segmented into Teams, you can apply unique queries and give users access to only the hosts in specific Teams.
You can add a host to a team by generating and using a unique osquery installer for a team or by [manually transferring a host to a team in the Fleet UI](../Using-Fleet/Teams.md#transfer-hosts-to-a-team).
To generate an osquery installer for a team:
1. First, create a team in Fleet by selecting "Create team" in **Settings > Teams**.
1. First, create a team in Fleet by selecting **Create team** in **Settings > Teams**.
2. Then, navigate to **Hosts** and select your team.
3. Next, select "Add hosts" and copy the `fleetctl package` command for the platform (macOS, Windows, Linux) of the hosts you'd like to add to a team in Fleet.
3. Next, select **Add hosts** and copy the `fleetctl package` command for the platform (macOS, Windows, Linux) of the hosts you'd like to add to a team in Fleet.
4. Run the copied `fleetctl package` command and [distribute your installer](#adding-multiple-hosts) to add your hosts to a team in Fleet.
### Configuration options
The following command-line flags allow you to further configure an osquery installer to communicate with a specific Fleet instance.
The following command-line flags allow you to configure an osquery installer further to communicate with a specific Fleet instance.
|Flag | Options|
|------|--------|
@ -119,27 +119,30 @@ Fleet supports other methods for adding your hosts to Fleet, such as the [plain
> If you'd like to use the native osqueryd binaries to connect to Fleet, this is enabled by using osquery's TLS API plugins that are principally documented on the official osquery wiki: http://osquery.readthedocs.io/en/stable/deployment/remote/. These plugins are very customizable and thus have a large configuration surface. Configuring osqueryd to communicate with Fleet is documented below in the "Native Osquery TLS Plugins" section.
You can find various ways to install osquery on a variety of platforms at https://osquery.io/downloads. Once you have installed osquery, you need to do two things:
You can find various ways to install osquery on various of platforms at https://osquery.io/downloads. Once you have installed osquery, you need to do two things:
- Set an environment variable with an enroll secret
- Deploy the TLS certificate that osquery will use to communicate with Fleet
### Set an environment variable with an enroll secret
The enroll secret is a value that osquery provides to authenticate with Fleet. There are a few ways you can set the enroll secret on the hosts which you control. You can either set the value as:
The enroll secret is a value that osquery provides to authenticate with Fleet. There are a few ways you can set the enroll secret on the hosts which you control. You can either set the value as
- an value of an environment variable (a common name is `OSQUERY_ENROLL_SECRET`)
- a value of an environment variable (a common name is `OSQUERY_ENROLL_SECRET`)
- the content of a local file (a common path is `/etc/osquery/enroll_secret`)
The value of the environment variable or content of the file should be a secret shared between the osqueryd client and the Fleet server. This is osqueryd's passphrase which it uses to authenticate with Fleet, convincing Fleet that it is actually one of your hosts. The passphrase could be whatever you'd like, but it would be prudent to have the passphrase long, complex, mixed-case, etc. When you launch the Fleet server, you should specify this same value.
If you use an environment variable for this, you can specify it with the `--enroll_secret_env` flag when you launch osqueryd. If you use a local file for this, you can specify it's path with the `--enroll_secret_path` flag.
If you use an environment variable for this, you can specify it with the `--enroll_secret_env` flag when you launch osqueryd. If you use a local file for this, you can specify its path with the `--enroll_secret_path` flag.
To retrieve the enroll secret, use the "Add New Host" dialog in the Fleet UI or
`fleetctl get enroll_secret`).
If your organization has a robust internal public key infrastructure (PKI) and you already deploy TLS client certificates to each host to uniquely identify them, then osquery supports an advanced authentication mechanism which takes advantage of this. Fleet can be fronted with a proxy that will perform the TLS client authentication.
If your organization has a robust internal public key infrastructure (PKI) and you already deploy TLS client certificates to each host to uniquely identify them, then osquery supports an advanced authentication mechanism that takes advantage of this. Fleet can be fronted with a proxy that will perform the TLS client authentication.
### Deploy the TLS certificate that osquery will use to communicate with Fleet
When Fleet uses a self-signed certificate, osquery agents will need a copy of that certificate in order to authenticate the Fleet server. If clients connect directly to the Fleet server, you can download the certificate through the Fleet UI. From the main dashboard (`/hosts/manage`), click "Add New Host" and "Fetch Certificate". If Fleet is running behind a load-balancer that terminates TLS, you will have to talk to your system administrator about where to find this certificate.
When Fleet uses a self-signed certificate, osquery agents will need a copy of that certificate in order to authenticate the Fleet server. If clients connect directly to the Fleet server, you can download the certificate through the Fleet UI. From the main dashboard (`/hosts/manage`), click **Add New Host** and **Fetch Certificate**. If Fleet is running behind a load-balancer that terminates TLS, you will have to talk to your system administrator about where to find this certificate.
It is important that the CN of this certificate matches the hostname or IP that osqueryd clients will use to connect.
@ -176,7 +179,7 @@ If your enroll secret is defined in a local file, specify the file's path with t
### Using a flag file to manage flags
For your convenience, osqueryd supports putting all of your flags into a single file. We suggest deploying this file to `/etc/osquery/fleet.flags`. If you've deployed the appropriate osquery flags to that path, you could simply launch osquery via:
For your convenience, osqueryd supports putting all your flags into a single file. We suggest deploying this file to `/etc/osquery/fleet.flags`. If you've deployed the appropriate osquery flags to that path, you could simply launch osquery via:
```
osqueryd --flagfile=/etc/osquery/fleet.flags
@ -184,7 +187,7 @@ osqueryd --flagfile=/etc/osquery/fleet.flags
#### Flag file on Windows
Ensure that paths to files in the flag file are absolute, and not quoted. For example in `C:\Program Files\osquery\osquery.flags`:
Make sure that paths to files in the flag file are absolute and not quoted. For example in `C:\Program Files\osquery\osquery.flags`:
```
--tls_server_certs=C:\Program Files\osquery\fleet.pem
@ -215,7 +218,7 @@ Test the installers on each platform before initiating the migration.
#### Migrate
Using your standard deployment tooling (Chef, Puppet, etc.), install the generated package. At this
Install the generated package using your standard deployment tooling (Chef, Puppet, etc.). At this
time, [uninstall the existing
osquery](https://blog.fleetdm.com/how-to-uninstall-osquery-f01cc49a37b9).
@ -223,7 +226,7 @@ If the existing enrolled hosts use `--host_identifier=uuid` (or the `uuid` setti
[osquery_host_identifier](../Deploying/Configuration.md#osquery-host-identifier)), the new
installation should appear as the same host in the Fleet UI. If other settings are used, duplicate
entries will appear in the Fleet UI. The older entries can be automatically cleaned up with the host
expiration functionality configured in the application settings (UI or fleetctl).
expiration setting. To configure this setting, in the Fleet UI, head to **Settings > Organization settings > Advanced options**.
## Grant full disk access to osquery on macOS
macOS does not allow applications to access all system files by default. If you are using MDM, which
@ -251,7 +254,7 @@ Executable=/opt/orbit/bin/orbit/macos/edge/orbit
designated => identifier "com.fleetdm.orbit" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "8VBZ3948LU"
```
> **NOTE:** Depending on the version of `fleetctl` used to package and install Orbit, the executable path may be different.
> **NOTE:** Depending on the version of `fleetctl` used to package and install Orbit, the executable path may differ.
> Fleetctl versions <= 4.13.2 would install orbit to `/var/lib/orbit` instead of `/opt/orbit`.
Note down the **executable path** and the entire **identifier**.
@ -261,10 +264,10 @@ Osqueryd will inherit the privileges from Orbit and does not need explicit permi
#### Creating the profile
Depending on your MDM, this might be possible in the UI or require a custom profile. If your MDM has a feature to configure *Policy Preferences*, follow these steps:
1. Configure the identifier type to “path”
1. Configure the identifier type to “path.”
2. Paste the full path to Orbit as the identifier.
3. Paste the full code signing identifier into the code requirement field.
4. Allow “Access all files”. Access to Downloads, Documents etc is inherited from this.
3. Paste the full code signing identifier into the Code requirement field.
4. Allow “Access all files.” Access to Downloads, Documents, etc., is inherited from this.
If your MDM does not have built-in support for privacy preferences profiles, you can use
[PPPC-Utility](https://github.com/jamf/PPPC-Utility) to create a profile with those values, then upload it to