Skip to content

Commit a7e666e

Browse files
ranbelranbel
authored
[ZT] Deploy WARP on headless Linux (#25439)
* service token API example * new tutorial * refine context * link from main MDM docs * mention email * warp client vs warp connector
1 parent ade9303 commit a7e666e

File tree

3 files changed

+158
-4
lines changed

3 files changed

+158
-4
lines changed

‎src/content/docs/cloudflare-one/connections/connect-devices/warp/deployment/mdm-deployment/index.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -140,9 +140,7 @@ The format of `/Library/Application Support/Cloudflare/mdm.xml` is as follows:
140140

141141
## Linux
142142

143-
The WARP client for Linux allows for an automated install via the presence of an `mdm.xml` file in `/var/lib/cloudflare-warp`.
144-
145-
The format of `/var/lib/cloudflare-warp/mdm.xml` is as follows:
143+
The WARP client for Linux allows for an automated install via the presence of an `mdm.xml` file in `/var/lib/cloudflare-warp`. The format of `/var/lib/cloudflare-warp/mdm.xml` is as follows:
146144

147145
```xml
148146
<dict>
@@ -153,6 +151,8 @@ The format of `/var/lib/cloudflare-warp/mdm.xml` is as follows:
153151

154152
Refer to [deployment parameters](/cloudflare-one/connections/connect-devices/warp/deployment/mdm-deployment/parameters/) for a list of accepted arguments.
155153

154+
To learn how to automate WARP deployment on headless servers, refer to our [tutorial](/cloudflare-one/tutorials/warp-on-headless-linux/).
155+
156156
## iOS
157157

158158
:::note[Migrate from 1.1.1.1]

‎src/content/docs/cloudflare-one/tutorials/warp-on-headless-linux.mdx‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
reviewed: 2025-09-26
3+
category: 🔐 Zero Trust
4+
difficulty: Beginner
5+
pcx_content_type: tutorial
6+
title: Deploy WARP on headless Linux machines
7+
---
8+
9+
import { Render, GlossaryTooltip } from "~/components";
10+
11+
This tutorial explains how to deploy the [Cloudflare WARP client](/cloudflare-one/connections/connect-devices/warp/) on Linux devices using a service token and an installation script. This deployment workflow is designed for headless servers - that is, servers which do not have access to a browser for identity provider logins - and for situations where you want to fully automate the onboarding process. Because devices will not register through an identity provider, [identity-based policies](/cloudflare-one/policies/gateway/identity-selectors/) and logging will be unavailable.
12+
13+
:::note
14+
This tutorial focuses on deploying WARP as an endpoint device agent. If you are looking to deploy WARP as a gateway to a private network, refer to the [WARP Connector documentation](/cloudflare-one/connections/connect-networks/private-net/warp-connector/).
15+
:::
16+
17+
## Prerequisites
18+
19+
- [Cloudflare Zero Trust account](/cloudflare-one/setup/#create-a-zero-trust-organization)
20+
21+
## 1. Create a service token
22+
23+
Fully automated deployments rely on a service token to enroll the WARP client in your Zero Trust organization. You can use the same token to enroll multiple devices, or generate a unique token per device if they require different [device profile settings](/cloudflare-one/connections/connect-devices/warp/configure-warp/device-profiles/).
24+
25+
To create a service token:
26+
27+
<Render file="access/create-service-token" product="cloudflare-one" />
28+
29+
## 2. Configure device enrollment permissions
30+
31+
Device enrollment permissions determine the users and devices that can register WARP with your Zero Trust organization.
32+
33+
To allow devices to enroll using a service token:
34+
35+
1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Settings** > **WARP Client**.
36+
2. In **Device enrollment permissions**, select **Manage**.
37+
3. In the **Policies** tab, select **Create new policy**. A new tab will open with the policy creation page.
38+
4. For **Action**, select _Service Auth_.
39+
5. For the **Selector** field, you have two options: you can either allow all service tokens (`Any Access Service Token`) or specific service tokens (`Service Token`). For example:
40+
41+
| Rule Action | Rule type | Selector | Value |
42+
| --------- | ---------| ------ | -- |
43+
| Service Auth | Include | Service Token | `<TOKEN-NAME>` |
44+
6. Save the policy.
45+
7. Go back to **Device enrollment permissions** and add the newly created policy to your permissions.
46+
8. Select **Save**.
47+
48+
## 3. Create an installation script
49+
50+
You can use a shell script to automate WARP installation and registration. The following example shows how to deploy WARP on Ubuntu 24.04.
51+
52+
1. In a terminal, create a new `.sh` file using a text editor. For example:
53+
```sh
54+
vim install_warp.sh
55+
```
56+
2. Press `i` to enter insert mode and add the following lines:
57+
58+
```bash
59+
#!/bin/bash
60+
set -e
61+
62+
# Download and install the WARP client
63+
function warp() {
64+
curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | sudo gpg --yes --dearmor --output /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg
65+
echo "deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflare-client.list
66+
sudo apt-get update --assume-yes
67+
sudo apt-get install --assume-yes cloudflare-warp
68+
}
69+
70+
# Create an MDM file with your WARP deployment parameters
71+
function mdm() {
72+
sudo touch /var/lib/cloudflare-warp/mdm.xml
73+
cat > /var/lib/cloudflare-warp/mdm.xml << "EOF"
74+
<dict>
75+
<key>auth_client_id</key>
76+
<string>88bf3b6d86161464f6509f7219099e57.access</string>
77+
<key>auth_client_secret</key>
78+
<string>bdd31cbc4dec990953e39163fbbb194c93313ca9f0a6e420346af9d326b1d2a5</string>
79+
<key>auto_connect</key>
80+
<integer>1</integer>
81+
<key>onboarding</key>
82+
<false/>
83+
<key>organization</key>
84+
<string>your-team-name</string>
85+
<key>service_mode</key>
86+
<string>warp</string>
87+
</dict>
88+
EOF
89+
}
90+
91+
#main program
92+
warp
93+
mdm
94+
```
95+
96+
3. If you are using Debian or RHEL / CentOS, modify the `warp()` function so that it installs the correct [WARP package](https://pkg.cloudflareclient.com/) for your OS.
97+
98+
4. Modify the values in the `mdm()` function:
99+
1. For `auth_client_id` and `auth_client_secret`, replace the string values with the Client ID and Client Secret of your [service token](/cloudflare-one/tutorials/warp-on-headless-linux/#1-create-a-service-token).
100+
2. For `organization`, replace `your-team-name` with your Zero Trust <GlossaryTooltip term="team name">team name</GlossaryTooltip>.
101+
3. (Optional) Add or modify other [WARP deployment parameters](/cloudflare-one/connections/connect-devices/warp/deployment/mdm-deployment/parameters/) according to your preferences.
102+
103+
5. Press `esc`, then type `:x` and press `Enter` to save and exit.
104+
105+
## 4. Install WARP
106+
107+
To install WARP using the example script:
108+
109+
1. Make the script executable:
110+
111+
```sh
112+
chmod +x install_warp.sh
113+
```
114+
115+
2. Run the script:
116+
```sh
117+
sudo ./install_warp.sh
118+
```
119+
120+
WARP is now deployed with the configuration parameters stored in `/var/lib/cloudflare-warp/mdm.xml`. Assuming [`auto_connect`](/cloudflare-one/connections/connect-devices/warp/deployment/mdm-deployment/parameters/#auto_connect) is configured, WARP will automatically connect to your Zero Trust organization. Once connected, the device will appear in [Zero Trust](https://one.dash.cloudflare.com) under **My Team** > **Devices** with the email `non_identity@<team-name>.cloudflareaccess.com`.

‎src/content/partials/cloudflare-one/access/create-service-token.mdx‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
---
55

6-
import { Tabs, TabItem, Details } from '~/components';
6+
import { Tabs, TabItem, Details, APIRequest } from '~/components';
77

88
<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
99

@@ -23,6 +23,40 @@ import { Tabs, TabItem, Details } from '~/components';
2323
This is the only time Cloudflare Access will display the Client Secret. If you lose the Client Secret, you must generate a new service token.
2424
:::
2525

26+
</TabItem> <TabItem label="API">
27+
28+
1. Make a `POST` request to the [Access Service Tokens](/api/resources/zero_trust/subresources/access/subresources/service_tokens/methods/create/) endpoint:
29+
30+
<APIRequest
31+
path="/accounts/{account_id}/access/service_tokens"
32+
method="POST"
33+
json={{
34+
name: "CI/CD token",
35+
duration: "8760h"
36+
}}
37+
/>
38+
39+
2. Copy the `client_id` and `client_secret` values returned in the response.
40+
41+
42+
```json title="Response" {2-3}
43+
"result": {
44+
"client_id": "88bf3b6d86161464f6509f7219099e57.access",
45+
"client_secret": "bdd31cbc4dec990953e39163fbbb194c93313ca9f0a6e420346af9d326b1d2a5",
46+
"created_at": "2025-09-25T22:26:26Z",
47+
"expires_at": "2026-09-25T22:26:26Z",
48+
"id": "3537a672-e4d8-4d89-aab9-26cb622918a1",
49+
"name": "CI/CD token",
50+
"updated_at": "2025-09-25T22:26:26Z",
51+
"duration": "8760h",
52+
"client_secret_version": 1
53+
}
54+
```
55+
56+
:::caution
57+
This is the only time Cloudflare Access will display the Client Secret. If you lose the Client Secret, you must generate a new service token.
58+
:::
59+
2660
</TabItem> <TabItem label="Terraform (v5)">
2761

2862
1. Add the following permission to your [`cloudflare_api_token`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_token):

0 commit comments

Comments
 (0)