Skip to content

Commit 2f894c4

Browse files
Maddy-CloudflareMaddy-Cloudflare
committed
[Magic Firewall] Restructure IA
1 parent ece3585 commit 2f894c4

File tree

6 files changed

+579
-0
lines changed

6 files changed

+579
-0
lines changed

‎src/content/docs/cloudflare-one/insights/network-visibility/diagnostics/buckets.mdx‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
title: Buckets
3+
pcx_content_type: how-to
4+
sidebar:
5+
order: 3
6+
---
7+
8+
import { GlossaryTooltip, TabItem, Tabs, DashButton } from "~/components";
9+
10+
Before you can begin a full <GlossaryTooltip term="data packet">packet</GlossaryTooltip> capture, you must first configure a bucket that Cloudflare can use to upload your files. Setting up a bucket is not required for sample packet captures.
11+
12+
You can configure an Amazon S3 or Google Cloud Platform bucket to use as a target. You can also [use R2](#r2) as a target using the API.
13+
14+
## Set up a bucket
15+
16+
Learn how to set up a bucket for use with full packet captures.
17+
18+
<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
19+
20+
1. In the Cloudflare One dashboard, go to the **Packet captures** page in Magic Transit or Magic WAN.
21+
22+
To set up a bucket in Magic Transit: <DashButton url="/?to=/:account/magic-transit/packet-captures/captures" />
23+
24+
To set up a bucket in Magic WAN: <DashButton url="/?to=/:account/magic-wan/packet-captures/captures" />
25+
2. Select the **Buckets** tab.
26+
3. Select **Add a bucket**.
27+
4. Under **Bucket configuration**, select a bucket service and select **Next**.
28+
5. Enter the information related to your bucket for your service provider.
29+
6. When you are done, select **Next**.
30+
31+
The **Prove ownership** step of the **Bucket configuration** displays.
32+
33+
</TabItem> <TabItem label="API">
34+
35+
Before you can begin using a bucket, you must first enable destinations.
36+
37+
Refer to the [Amazon S3](/logs/logpush/logpush-job/enable-destinations/aws-s3/#create-and-get-access-to-an-s3-bucket) or [Google Cloud Storage](/logs/logpush/logpush-job/enable-destinations/google-cloud-storage/#create-and-get-access-to-a-gcs-bucket) documentation and follow the steps for those specific services.
38+
39+
</TabItem> </Tabs>
40+
41+
Next, validate the bucket and confirm ownership.
42+
43+
## Validate a bucket
44+
45+
After the initial bucket set up, you need to confirm you own the bucket via an ownership challenge. After you validate your bucket, you can begin using it to collect full packet captures.
46+
47+
<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
48+
49+
1. From the **Prove ownership** step of the **Bucket configuration**, locate the **Ownership token** field.
50+
2. In the **Ownership token** field, enter the ownership token for your service provider.
51+
3. When you are done, select **Create**. The **Packet captures** page displays.
52+
53+
The **Buckets** tab displays a list of the buckets associated with your account. Refer to the **Status** column to see the status of your bucket configuration.
54+
55+
</TabItem> <TabItem label="API">
56+
57+
The `bucket` field should be the URI of the bucket. For Amazon S3, the `bucket` field is in the form `s3://<bucket-name>/<directory>?region=<bucket-region>`, and for Google Cloud Storage the form is `gs://<bucket-name>/<directory>`.
58+
59+
```bash title="Ownership challenge request example"
60+
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/pcaps/ownership \
61+
--header "X-Auth-Email: <EMAIL>" \
62+
--header "X-Auth-Key: <API_KEY>" \
63+
--header "Content-Type: application/json" \
64+
--data '{
65+
"destination_conf": "'${bucket}'"
66+
}'
67+
```
68+
69+
The response has a `"filename"` parameter which contains the content of the `ownership-challenge` text. Find the file in your bucket and copy the contents of the file.
70+
71+
```json title="Ownership challenge response example"
72+
{
73+
"result": {
74+
"id": "cc20c2d6c62e11ecbe646b173af3b6b9",
75+
"status": "pending",
76+
"submitted": "2022-04-22T18:54:13.397413Z",
77+
"validated": "",
78+
"destination_conf": "gs://bucket-test", // Ensure you use a bucket that you created and registered in the Cloudflare dashboard.
79+
"filename": "ownership-challenge-1234.txt"
80+
},
81+
"success": true,
82+
"errors": [],
83+
"messages": []
84+
}
85+
```
86+
87+
Validate the bucket by inserting the copied text in the `ownership_text` below:
88+
89+
```bash title="Bucket validation example"
90+
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/pcaps/ownership/validate \
91+
--header "X-Auth-Email: <EMAIL>" \
92+
--header "X-Auth-Key: <API_KEY>" \
93+
--header "Content-Type: application/json" \
94+
--data '{
95+
"destination_conf": "'${bucket}'",
96+
"ownership_challenge": "'${ownership_text}'"
97+
}'
98+
```
99+
100+
```json title="Bucket validation response"
101+
{
102+
"result": {
103+
"id": "cc20c2d6c62e11ecbe646b173af3b6b9",
104+
"status": "success",
105+
"submitted": "2022-04-22T18:54:13.397413Z",
106+
"validated": "2022-04-27T14:54:46.440548Z",
107+
"destination_conf": "gs://<bucket-name>", // Ensure you use a bucket that you created and registered in the Cloudflare dashboard
108+
"filename": "ownership-challenge-1234.txt"
109+
},
110+
"success": true,
111+
"errors": [],
112+
"messages": []
113+
}
114+
```
115+
116+
If the `status` shows `success`, the bucket is configured and ready to use.
117+
118+
</TabItem> </Tabs>
119+
120+
The bucket status displays one of the following options:
121+
122+
- **Success:** The bucket is fully verified and ready to use.
123+
- **Pending:** The challenge response was initiated but is pending verification. Bucket verification can take five to ten minutes to finish processing.
124+
- **Failed:** The bucket could not be validated. If this occurs, verify your ownership information.
125+
126+
## List configured buckets
127+
128+
View a list of all buckets configured on your account.
129+
130+
<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
131+
132+
1. In the Cloudflare One dashboard, go to the **Packet captures** page in Magic Transit or Magic WAN.
133+
134+
To set up a packet capture in Magic Transit: <DashButton url="/?to=/:account/magic-transit/packet-captures/captures" />
135+
136+
To set up a packet capture in Magic WAN: <DashButton url="/?to=/:account/magic-wan/packet-captures/captures" />
137+
2. In **Packet captures**, select **Start a capture**.
138+
3. Select the **Buckets** tab.
139+
140+
The list of buckets associated with your account displays.
141+
142+
</TabItem> <TabItem label="API">
143+
144+
```bash title="Bucket list request example"
145+
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/pcaps/ownership \
146+
--header "X-Auth-Email: <EMAIL>" \
147+
--header "X-Auth-Key: <API_KEY>"
148+
```
149+
150+
```json title="Bucket list response example"
151+
{
152+
"result": [
153+
{
154+
"id": "9a993aa6c58711ec89d3037647342e63",
155+
"status": "success",
156+
"submitted": "2022-04-26T16:58:24.550762Z",
157+
"validated": "2022-04-26T17:01:18.426458Z",
158+
"destination_conf": "s3://test-bucket?region=us-east-1",
159+
"filename": "ownership-challenge-1234.txt"
160+
}
161+
],
162+
"success": true,
163+
"errors": [],
164+
"messages": []
165+
}
166+
```
167+
168+
</TabItem> </Tabs>
169+
170+
To learn how to collect packet captures, refer to [Collect packet captures](/magic-firewall/packet-captures/collect-pcaps/).
171+
172+
## R2
173+
174+
To start collecting packet captures with R2, you first need to configure it properly. For all the required details, refer to the [Cloudflare R2](/r2/) documentation.
175+
176+
### Create bucket and API token
177+
178+
1. In the Cloudflare One dashboard, go to the **R2** page.
179+
180+
<DashButton url="/?to=/:account/r2/overview" />
181+
182+
2. Select **Create bucket**.
183+
3. Give your bucket a name > **Create bucket**.
184+
4. Go to the R2 Overview page, and select **Manage R2 API Tokens**.
185+
5. Select **Create API Token**.
186+
6. In **Permissions**, choose **Object Read & Write**. Make sure you also select **Apply to specific buckets only**, and select the bucket you have created for PCAPs from the drop-down menu.
187+
7. Select **Create API Token**.
188+
8. Make sure you copy the **Secret Access Key** and **Access Key ID** values, as you will need them for the next step.
189+
190+
### Create initial request
191+
192+
Create your initial request to R2:
193+
194+
```bash
195+
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/pcaps/ownership \
196+
--header "X-Auth-Email: <EMAIL>" \
197+
--header "X-Auth-Key: <API_KEY>" \
198+
--header "Content-Type: application/json" \
199+
--data '{
200+
"destination_conf": "r2://<BUCKET_NAME>?account-id=<ACCOUNT_ID>&access-key-id=<R2_ACCESS_KEY_ID>&secret-access-key=<R2_SECRET_ACCESS_KEY>"
201+
}'
202+
```
203+
204+
The [response](/api/resources/magic_transit/subresources/pcaps/subresources/ownership/methods/create/) has a `"filename"` parameter with the name of a file that Cloudflare wrote to your R2 bucket. You need to download it for the next step. Example:
205+
206+
```json
207+
{
208+
"errors": [],
209+
"messages": [],
210+
"result": {
211+
"destination_conf": "<YOUR_R2_BUCKET>",
212+
"filename": "ownership-challenge-9883874ecac311ec8475433579a6bf5f.txt",
213+
"id": "9883874ecac311ec8475433579a6bf5f",
214+
"status": "success",
215+
"submitted": "2020-01-01T08:00:00Z",
216+
"validated": "2020-01-01T08:00:00Z"
217+
},
218+
"success": true
219+
}
220+
```
221+
222+
### Validate bucket ownership
223+
224+
Refer to the [Validate a bucket](#validate-a-bucket) API instructions for more details on the entire process to [validate your R2 bucket](/api/resources/magic_transit/subresources/pcaps/subresources/ownership/methods/validate/). When specifying the R2 destination for this validation, exclude the secret and access keys from the URL.

‎src/content/docs/cloudflare-one/insights/network-visibility/diagnostics/index.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Diagnostics
3+
pcx_content_type: navigation
4+
sidebar:
5+
order: 1
6+
7+
---
8+
9+
import { DirectoryListing } from "~/components"
10+
11+
Cloudflare supports two types of packet captures: full and sample. Full packet captures is the default behavior.
12+
13+
:::note
14+
The maximum packet capture runtime is 24 hours for sample and full packet captures.
15+
:::
16+
17+
## Sample packet captures
18+
19+
Sample packet captures collects historical data on network traffic that has already passed through Cloudflare's network. It will not collect any new traffic sent to Cloudflare's network after the packet capture has started. All sample packet captures will complete immediately after they are started because they query historical traffic data.
20+
21+
Sample packet captures can be viewed in the Cloudflare dashboard. They only include the first 160 bytes of data. This is useful for capturing packet headers, but will not provide detailed packet data. The sample data is collected across all Cloudflare's data centers to build a PCAP file. This allows you to get a global picture of traffic across all data centers.
22+
23+
You should use full packet captures if you need to collect data on packets that pass through your network less frequently.
24+
25+
## Full packet captures
26+
27+
Full packet captures will actively monitor Cloudflare's network for packets that match the selected filters, and will capture the matching packet data. The matching packet data is saved to a cloud storage bucket that is owned and configured by you.
28+
29+
Full packet captures will collect new traffic sent to Cloudflare's network after the packet capture has started, and include the full packet data. This type of capture cannot be viewed in the Cloudflare dashboard. You can download them from a cloud storage bucket and analyze them in Wireshark or another packet capture tool.
30+
31+
Refer to the articles in this section to learn how to use packet captures.
32+
33+
<DirectoryListing />

0 commit comments

Comments
 (0)