Skip to content

Commit 7f90e3e

Browse files
didier-wenzekdidier-wenzek
committed
Adding examples to tedge http --help
Signed-off-by: Didier Wenzek <[email protected]>
1 parent fed0a1c commit 7f90e3e

File tree

2 files changed

+265
-0
lines changed

2 files changed

+265
-0
lines changed

‎crates/core/tedge/src/cli/http/cli.rs‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,18 @@ use tedge_config::ProfileName;
1818
#[derive(clap::Subcommand, Debug)]
1919
pub enum TEdgeHttpCli {
2020
/// POST content to thin-edge local HTTP servers
21+
///
22+
/// Examples:
23+
/// # Create a new Cumulocity Managed Object via the proxy service
24+
/// tedge http post /c8y/inventory/managedObjects '{"name":"test"}' --accept-type application/json
25+
///
26+
/// # Create a new child device
27+
/// tedge http post /tedge/entity-store/v1/entities '{
28+
/// "@topic-id": "device/a//",
29+
/// "@type": "child-device",
30+
/// "@parent": "device/main//"
31+
/// }'
32+
#[clap(verbatim_doc_comment)]
2133
Post {
2234
/// Target URI
2335
uri: String,
@@ -42,6 +54,14 @@ pub enum TEdgeHttpCli {
4254
},
4355

4456
/// PUT content to thin-edge local HTTP servers
57+
///
58+
/// Examples:
59+
/// # Upload file to the file transfer service
60+
/// tedge http put /tedge/file-transfer/target.txt --file source.txt
61+
///
62+
/// # Update a Cumulocity Managed Object. Note: Assuming tedge is the owner of the managed object
63+
/// tedge http put /c8y/inventory/managedObjects/2343978440 '{"name":"item A"}' --accept-type application/json
64+
#[clap(verbatim_doc_comment)]
4565
Put {
4666
/// Target URI
4767
uri: String,
@@ -66,6 +86,14 @@ pub enum TEdgeHttpCli {
6686
},
6787

6888
/// GET content from thin-edge local HTTP servers
89+
///
90+
/// Examples:
91+
/// # Download file from the file transfer service
92+
/// tedge http get /tedge/file-transfer/target.txt
93+
///
94+
/// # Download file from Cumulocity's binary api
95+
/// tedge http get /c8y/inventory/binaries/104332 > my_file.bin
96+
#[clap(verbatim_doc_comment)]
6997
Get {
7098
/// Source URI
7199
uri: String,
@@ -81,6 +109,14 @@ pub enum TEdgeHttpCli {
81109
},
82110

83111
/// DELETE resource from thin-edge local HTTP servers
112+
///
113+
/// Examples:
114+
/// # Delete a file from the file transfer service
115+
/// tedge http delete /tedge/file-transfer/target.txt
116+
///
117+
/// # Delete a Cumulocity managed object. Note: Assuming tedge is the owner of the managed object
118+
/// tedge http delete /c8y/inventory/managedObjects/2343978440
119+
#[clap(verbatim_doc_comment)]
84120
Delete {
85121
/// Source URI
86122
uri: String,

‎docs/src/references/cli/tedge-http.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
---
2+
title: "tedge http"
3+
tags: [Reference, CLI]
4+
sidebar_position: 6
5+
---
6+
7+
# The tedge http command
8+
9+
A `tedge` sub command to interact with the HTTP services hosted on the device by the Cumulocity mapper and the agent:
10+
11+
- the [Cumulocity Proxy](/references/cumulocity-proxy/)
12+
- the [File Transfer Service](/references/file-transfer-service/)
13+
- the [Entity Store Service](/operate/registration/register/).
14+
15+
This command uses `tedge config` to get the appropriate host, port and credentials to reach these local HTTP services.
16+
So the same command can be used unchanged from the main device or a child device, with TLS or mTLS enabled or not.
17+
18+
```sh title="tedge http"
19+
Send HTTP requests to local thin-edge HTTP servers
20+
21+
Usage: tedge http [OPTIONS] <COMMAND>
22+
23+
Commands:
24+
post POST content to thin-edge local HTTP servers
25+
put PUT content to thin-edge local HTTP servers
26+
get GET content from thin-edge local HTTP servers
27+
delete DELETE resource from thin-edge local HTTP servers
28+
help Print this message or the help of the given subcommand(s)
29+
30+
Options:
31+
--config-dir <CONFIG_DIR> [env: TEDGE_CONFIG_DIR, default: /etc/tedge]
32+
--debug Turn-on the DEBUG log level
33+
--log-level <LOG_LEVEL> Configures the logging level
34+
-h, --help Print help (see more with '--help')
35+
```
36+
37+
## %%te%% HTTP services {#http-services}
38+
39+
40+
`tedge http` forwards requests to the appropriate %%te%% HTTP service using the URL prefixes.
41+
42+
The requests are forwarded to the appropriate service depending on the URL prefix.
43+
44+
- URIs prefixed by `/c8y/` are forwarded to the [Cumulocity Proxy](/references/cumulocity-proxy/)
45+
46+
```sh title="Interacting with Cumulocity"
47+
tedge http get /c8y/inventory/managedObjects
48+
```
49+
50+
- URIs starting with `/tedge/file-transfer/` are directed to the [File Transfer Service](/references/file-transfer-service)
51+
52+
```sh title="Transferring files to/from the main device"
53+
tedge http put /tedge/file-transfer/target.txt --file source.txt
54+
```
55+
56+
- URIs starting with `/tedge/entity-store` are directed to the [Entity Store Service](/operate/registration/register)
57+
58+
```sh title="Listing all entities"
59+
tedge http get /tedge/entity-store/v1/entities
60+
```
61+
62+
63+
## Configuration
64+
65+
For `tedge http` to be used from the main device or any client device, with TLS or mTLS enabled or not,
66+
the host, port and credentials of the local %%te%% HTTP services
67+
have to be properly configured on the main device as well as the child devices.
68+
69+
### On the host running the main agent
70+
71+
The following `tedge config` settings control the access granted to child devices
72+
on the HTTP services provided by the main agent
73+
([file transfer](/references/file-transfer-service) and entity registration).
74+
This can be done along three security levels.
75+
76+
```sh title="Listening HTTP requests"
77+
http.bind.port The port number of the File Transfer Service HTTP server binds to for internal use.
78+
Example: 8000
79+
http.bind.address The address of the File Transfer Service HTTP server binds to for internal use.
80+
Examples: 127.0.0.1, 192.168.1.2, 0.0.0.0
81+
```
82+
83+
```sh title="Enabling TLS aka HTTPS"
84+
http.cert_path The file that will be used as the server certificate for the File Transfer Service.
85+
Example: /etc/tedge/device-certs/file_transfer_certificate.pem
86+
http.key_path The file that will be used as the server private key for the File Transfer Service.
87+
Example: /etc/tedge/device-certs/file_transfer_key.pem
88+
```
89+
90+
```sh title="Enforcing mTLS"
91+
http.ca_path Path to a directory containing the PEM encoded CA certificates that are trusted when checking incoming client certificates for the File Transfer Service.
92+
Example: /etc/ssl/certs
93+
```
94+
95+
### On the host running the cumulocity mapper
96+
97+
The following `tedge config` settings control the access granted to child devices
98+
on the HTTP services provided by the Cumulocity mapper ([Cumulocity proxy](/references/cumulocity-proxy/)).
99+
This can be done along three security levels.
100+
101+
```sh title="Listening HTTP requests"
102+
c8y.proxy.bind.address The IP address local Cumulocity HTTP proxy binds to.
103+
Example: 127.0.0.1
104+
c8y.proxy.bind.port The port local Cumulocity HTTP proxy binds to.
105+
Example: 8001
106+
```
107+
108+
```sh title="Enabling TLS aka HTTPS"
109+
c8y.proxy.cert_path The file that will be used as the server certificate for the Cumulocity proxy.
110+
Example: /etc/tedge/device-certs/c8y_proxy_certificate.pem
111+
c8y.proxy.key_path The file that will be used as the server private key for the Cumulocity proxy.
112+
Example: /etc/tedge/device-certs/c8y_proxy_key.pem
113+
```
114+
115+
```sh title="Enforcing mTLS"
116+
c8y.proxy.ca_path Path to a file containing the PEM encoded CA certificates that are trusted when checking incoming client certificates for the Cumulocity Proxy.
117+
Example: /etc/ssl/certs
118+
```
119+
120+
### On all client hosts
121+
122+
The following `tedge config` settings control how client devices access the local HTTP services.
123+
This has to be done in consistent way with the main agent and Cumulocity mapper settings.
124+
125+
```sh title="Reaching local HTTP services"
126+
http.client.port The port number on the remote host on which the File Transfer Service HTTP server is running.
127+
Example: 8000
128+
http.client.host The address of the host on which the File Transfer Service HTTP server is running.
129+
Examples: 127.0.0.1, 192.168.1.2, tedge-hostname
130+
c8y.proxy.client.host The address of the host on which the local Cumulocity HTTP Proxy is running, used by the Cumulocity mapper.
131+
Examples: 127.0.0.1, 192.168.1.2, tedge-hostname
132+
c8y.proxy.client.port The port number on the remote host on which the local Cumulocity HTTP Proxy is running, used by the Cumulocity mapper.
133+
Example: 8001
134+
```
135+
136+
```sh title="Using TLS aka HTTPS"
137+
http.ca_path Path to a directory containing the PEM encoded CA certificates that are trusted when checking incoming client certificates for the File Transfer Service.
138+
Example: /etc/ssl/certs
139+
c8y.proxy.ca_path Path to a file containing the PEM encoded CA certificates that are trusted when checking incoming client certificates for the Cumulocity Proxy.
140+
Example: /etc/ssl/certs
141+
```
142+
143+
```sh title="Using mTLS"
144+
http.client.auth.cert_file Path to the certificate which is used by the agent when connecting to external services.
145+
http.client.auth.key_file Path to the private key which is used by the agent when connecting to external services.
146+
```
147+
148+
## tedge http post
149+
150+
```sh title="tedge http post"
151+
POST content to thin-edge local HTTP servers
152+
153+
Usage: tedge http post [OPTIONS] <content|--data <DATA>|--file <FILE>> <URI>
154+
155+
Arguments:
156+
<URI> Target URI
157+
[content] Content to send
158+
159+
Options:
160+
--config-dir <CONFIG_DIR> [env: TEDGE_CONFIG_DIR, default: /etc/tedge]
161+
--data <DATA> Content to send
162+
--debug Turn-on the DEBUG log level
163+
--file <FILE> File which content is sent
164+
--content-type <CONTENT_TYPE> MIME type of the content
165+
--log-level <LOG_LEVEL> Configures the logging level
166+
--accept-type <ACCEPT_TYPE> MIME type of the expected content
167+
--profile <PROFILE> Optional c8y cloud profile
168+
-h, --help Print help (see more with '--help')
169+
```
170+
171+
## tedge http put
172+
173+
```sh title="tedge http put"
174+
PUT content to thin-edge local HTTP servers
175+
176+
Usage: tedge http put [OPTIONS] <content|--data <DATA>|--file <FILE>> <URI>
177+
178+
Arguments:
179+
<URI> Target URI
180+
[content] Content to send
181+
182+
Options:
183+
--config-dir <CONFIG_DIR> [env: TEDGE_CONFIG_DIR, default: /etc/tedge]
184+
--data <DATA> Content to send
185+
--debug Turn-on the DEBUG log level
186+
--file <FILE> File which content is sent
187+
--content-type <CONTENT_TYPE> MIME type of the content
188+
--log-level <LOG_LEVEL> Configures the logging level
189+
--accept-type <ACCEPT_TYPE> MIME type of the expected content
190+
--profile <PROFILE> Optional c8y cloud profile
191+
-h, --help Print help (see more with '--help')
192+
```
193+
194+
## tedge http get
195+
196+
```sh title="tedge http get"
197+
GET content from thin-edge local HTTP servers
198+
199+
Usage: tedge http get [OPTIONS] <URI>
200+
201+
Arguments:
202+
<URI> Source URI
203+
204+
Options:
205+
--accept-type <ACCEPT_TYPE> MIME type of the expected content
206+
--config-dir <CONFIG_DIR> [env: TEDGE_CONFIG_DIR, default: /etc/tedge]
207+
--debug Turn-on the DEBUG log level
208+
--profile <PROFILE> Optional c8y cloud profile
209+
--log-level <LOG_LEVEL> Configures the logging level
210+
-h, --help Print help (see more with '--help')
211+
```
212+
213+
## tedge http delete
214+
215+
```sh title="tedge http delete"
216+
DELETE resource from thin-edge local HTTP servers
217+
218+
Usage: tedge http delete [OPTIONS] <URI>
219+
220+
Arguments:
221+
<URI> Source URI
222+
223+
Options:
224+
--config-dir <CONFIG_DIR> [env: TEDGE_CONFIG_DIR, default: /etc/tedge]
225+
--profile <PROFILE> Optional c8y cloud profile
226+
--debug Turn-on the DEBUG log level
227+
--log-level <LOG_LEVEL> Configures the logging level
228+
-h, --help Print help (see more with '--help')
229+
```

0 commit comments

Comments
 (0)