Skip to content

Commit

Permalink
Merge branch 'faq-breakout' of https://github.com/open-amt-cloud-tool…
Browse files Browse the repository at this point in the history 
…kit/docs into faq-breakout
  • Loading branch information
@bwendlandt-intel
bwendlandt-intel committed Sep 27, 2023
2 parents 1e8763b + 601ce7e commit 3e82c99
Show file tree
Hide file tree
Showing 12 changed files with 149 additions and 230 deletions.
4 changes: 3 additions & 1 deletion docs/GetStarted/buildRPC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,12 +63,14 @@ If you are building an executable on a development system, you will copy the exe

3. Confirm a successful build:

RPC must run with elevated privileges. Commands require `sudo` on Linux or an Administrator Command Prompt on Windows.

=== "Linux"
``` bash
sudo ./rpc version
```
=== "Windows"
``` bash
```
.\rpc version
```
=== "Docker (On Linux Host Only)"
Expand Down
11 changes: 3 additions & 8 deletions docs/Reference/Certificates/generateProvisioningCert.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -198,14 +198,9 @@ First, we need to prepare two files:
The new hash should be listed.
=== "Linux"
``` bash
sudo ./rpc amtinfo -cert
```
=== "Windows"
```
.\rpc amtinfo -cert
```
```
rpc amtinfo -cert
```
!!! success "Success - Hash Inserted Correctly"
<figure class="figure-image">
Expand Down
2 changes: 2 additions & 0 deletions docs/Reference/RPC/buildRPC_Manual.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,8 @@ Developed in Go* programming language, the Remote Provisioning Client (RPC) appl

2. Confirm a successful build:

RPC must run with elevated privileges. Commands require `sudo` on Linux or an Administrator Command Prompt on Windows.

=== "Linux"
``` bash
sudo ./rpc version
Expand Down
153 changes: 63 additions & 90 deletions docs/Reference/RPC/commandsRPC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,14 @@
On the managed device, a Remote Provisioning Client (RPC) communicates with the Remote Provision Server (RPS) in the process of activating or deactivating the device. In addition to activation and deactivation, the RPC provides informational and maintenance commands.

## List Commands
On the managed device, open a Terminal (Linux) or Powershell/Command Prompt **as Administrator** (Windows).

RPC must run with elevated privileges. Commands require `sudo` on Linux or an Administrator Command Prompt on Windows.

Run the RPC application on the command line with no arguments to see supported commands:

=== "Linux"
``` bash
sudo ./rpc
```
=== "Windows"
```
.\rpc.exe
```
```
rpc
```

| COMMAND | DESCRIPTION | EXAMPLE |
|-----------------------------|---------------------------------------------------------------------------------------------|--------------------------------------------------------------|
Expand All @@ -29,42 +25,47 @@ Run the RPC application on the command line with no arguments to see supported c

Run the application with a command to see available options for the command:

=== "Linux"
``` bash
sudo ./rpc [COMMAND]
```
=== "Windows"
```
.\rpc [COMMAND]
```
```
rpc [COMMAND]
```

### activate

#### Activate and Configure the device using RPS:

Activate the device with a specified profile:

=== "Linux"
``` bash
sudo ./rpc activate -u wss://server/activate -profile profilename
```
=== "Windows"
```
.\rpc activate -u wss://server/activate -profile profilename
```
```
rpc activate -u wss://server/activate -profile profilename
```

#### Activate the device locally:

This capability is only supported for activating unprovisioned (e.g. pre-provisioning state) devices. This command **only** activates AMT. It does not do profile-based configuration.

=== "CCM"
```
rpc activate -local -ccm -amtPassword NewAMTPassword
rpc activate -local -ccm -password NewAMTPassword
```
=== "ACM"
```
rpc activate -local -acm -amtPassword NewAMTPassword -provisioningCert "{BASE64_PROV_CERT}" -provivisioningCertPwd certPassword
```
=== "ACM w/ Config File"
Options can be passed via a config file. This can also be combined into a single config file with [addwifisettings](#addwifisettings) information.

=== "YAML"
```yaml title="config.yaml"
acmactivate:
amtPassword: 'P@ssw0rd'
provisioningCert: 'BASE64_PROV_CERT'
provivisioningCertPwd: 'CertP@ssw0rd'
```

Example Command
```
rpc activate -local -acm -config config.yaml
```

<br>

Expand Down Expand Up @@ -102,6 +103,7 @@ This capability is only supported for activating unprovisioned (e.g. pre-provisi
| -acm | Flag for ACM Local Activation. |
| -amtPassword string | New AMT Password to set on device. |
| -ccm | Flag for CCM Local Activation. |
| -config | File path of a `.yaml` file with desired ACM configuration. |
| -local | Execute command to AMT directly without cloud interaction. |
| -provisioningCert Base64 string | Base64 Encoded String of the `.pfx` provisioning certificate. |
| -provisioningCertPwd string | Password of provisioning certificate. |
Expand Down Expand Up @@ -194,14 +196,9 @@ Execute a maintenance command for the managed device:

Change the AMT password. A random password is generated by default if `static` option is not passed.

=== "Linux"
``` bash
sudo ./rpc maintenance changepassword -u wss://server/maintenance
```
=== "Windows"
```
.\rpc maintenance changepassword -u wss://server/maintenance
```
```
rpc maintenance changepassword -u wss://server/maintenance
```

| OPTION | DESCRIPTION |
|---------|-------------------------|
Expand All @@ -213,44 +210,29 @@ Change the AMT password. A random password is generated by default if `static` o

Syncs the host OS clock to AMT.

=== "Linux"
``` bash
sudo ./rpc maintenance syncclock -u wss://server/maintenance
```
=== "Windows"
```
.\rpc maintenance syncclock -u wss://server/maintenance
```
```
rpc maintenance syncclock -u wss://server/maintenance
```

<br>

#### synchostname

Sync the OS hostname to AMT Network Settings.

=== "Linux"
``` bash
sudo ./rpc maintenance synchostname -u wss://server/maintenance
```
=== "Windows"
```
.\rpc maintenance synchostname -u wss://server/maintenance
```
```
rpc maintenance synchostname -u wss://server/maintenance
```

<br>

#### syncip

Sync the static IP of host OS to AMT Network Settings.

=== "Linux"
```
sudo ./rpc maintenance syncip -staticip 192.168.1.7 -netmask 255.255.255.0 -gateway 192.168.1.1 -primarydns 8.8.8.8 -secondarydns 4.4.4.4 -u wss://server/maintenance
```
=== "Windows"
```
.\rpc maintenance syncip -staticip 192.168.1.7 -netmask 255.255.255.0 -gateway 192.168.1.1 -primarydns 8.8.8.8 -secondarydns 4.4.4.4 -u wss://server/maintenance
```
```
rpc maintenance syncip -staticip 192.168.1.7 -netmask 255.255.255.0 -gateway 192.168.1.1 -primarydns 8.8.8.8 -secondarydns 4.4.4.4 -u wss://server/maintenance
```

| OPTION | DESCRIPTION |
|---------------|---------------------------------------------------------------------------------------------------------------------|
Expand Down Expand Up @@ -543,33 +525,29 @@ On failure, the `addwifisettings` maintenance command will rollback any certific

Display AMT status and configuration:

=== "Linux"
``` bash
sudo ./rpc amtinfo [OPTIONS]
```
=== "Windows"
```
.\rpc amtinfo [OPTIONS]
```
```
rpc amtinfo [OPTIONS]
```

**Not passing `[OPTIONS]` will print all information.**

| AMT INFO | OPTION | DESCRIPTION |
|-------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| | -json | JSON Output |
| Version | -ver | Intel AMT version. |
| Build Number | -bld | Intel AMT Build Number. |
| Certificate | -cert | Certificate Hashes |
| SKU | -sku | Product SKU |
| UUID | -uuid | Unique Universal Identifier of the device. Used when creating device-specific MPS API calls as part of the REST API's URL path. |
| Control Mode | -mode | Control Mode below indicates the managed device's state: <br>(a) pre-provisioning state <br>(b) activated in client control mode <br>(c) activated in admin control mode |
| DNS Suffix | -dns | DNS Suffix set according to PKI DNS Suffix in Intel MEBX or through DHCP Option 15. Requried for ACM activation. |
| DNS Suffix (OS) | -dns | |
| Hostname (OS) | -hostname | Device's hostname as set in the Operating System. |
| RAS Network | -ras | |
| RAS Remote Status | -ras | Unconnected or connected. State of connection to a management server. |
| RAS Trigger | -ras | User initiated or periodic. When activated, periodic signifies CIRA established. By default, CIRA sends a heartbeat to the server every 30 seconds to verify and maintain connection. |
| RAS MPS Hostname | -ras | IP Address or FQDN of the MPS server. |
| AMT INFO | OPTION | DESCRIPTION |
|----------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| | -json | JSON Output |
| Version | -ver | Intel AMT version. |
| Build Number | -bld | Intel AMT Build Number. |
| System Certificates | -cert | System Certificate Hashes. If given `-password`, will print both System and User Certificate Hashes. |
| User Certificates | -userCert | User Certificate Hashes. Will prompt for AMT password. Or, provide `-password` flag. |
| SKU | -sku | Product SKU |
| UUID | -uuid | Unique Universal Identifier of the device. Used when creating device-specific MPS API calls as part of the REST API's URL path. |
| Control Mode | -mode | Control Mode below indicates the managed device's state: <br>(a) pre-provisioning state <br>(b) activated in client control mode <br>(c) activated in admin control mode |
| DNS Suffix | -dns | DNS Suffix set according to PKI DNS Suffix in Intel MEBX or through DHCP Option 15. Requried for ACM activation. |
| DNS Suffix (OS) | -dns | |
| Hostname (OS) | -hostname | Device's hostname as set in the Operating System. |
| RAS Network | -ras | |
| RAS Remote Status | -ras | Unconnected or connected. State of connection to a management server. |
| RAS Trigger | -ras | User initiated or periodic. When activated, periodic signifies CIRA established. By default, CIRA sends a heartbeat to the server every 30 seconds to verify and maintain connection. |
| RAS MPS Hostname | -ras | IP Address or FQDN of the MPS server. |

**---Wired/Wireless Adapters---**

Expand All @@ -588,11 +566,6 @@ see [Wireless Activation](../../Tutorials/createWiFiConfig.md).

Display the current version of RPC and the RPC Protocol version:

=== "Linux"
``` bash
sudo ./rpc version
```
=== "Windows"
```
.\rpc version
```
```
rpc version
```
43 changes: 29 additions & 14 deletions docs/Reference/RPC/libraryRPC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,12 @@ This sample provides an example of calling the `rpcExec` function to activate a
|25 |Missing hostname |
|26 |Missing proxy address and port |
|27 |Missing static IP information |
|28 |Incorrect Command Line Parameters |
|29 |Missing or incorrect Network Mask |
|30 |Missing or incorrect Gateway |
|31 |Missing or incorrect Primary DNS |
|32 |Missing or incorrect Secondary DNS |
|33 |Invalid Parameter Combination |

#### (70-99) Connection Errors

Expand All @@ -121,22 +127,31 @@ This sample provides an example of calling the `rpcExec` function to activate a

#### (100-149) Activation and Configuration Errors

|Error Code| Message |
|----------|-----------------------------------------|
|100 |AMT authentication failed |
|101 |WSMAN message error |
|102 |Activation failed |
|103 |Network configuration failed |
|104 |CIRA configuration failed |
|105 |TLS configuration failed |
|106 |WiFi configuration failed |
|107 |AMT features configuration failed |
|108 |802.1x configuration failed |
|Error Code| Message |
|----------|-------------------------------------------|
|100 |AMT authentication failed |
|101 |WSMAN message error |
|102 |Activation failed |
|103 |Network configuration failed |
|104 |CIRA configuration failed |
|105 |TLS configuration failed |
|106 |WiFi configuration failed |
|107 |AMT features configuration failed |
|108 |802.1x configuration failed |
|109 |Unable to Deactivate |
|110 |Deactivation Failed |
|111 |Unable to Activate |
|112 |Wifi Configuration succeeded with warnings |
|113 |Unmarshal Message Failed |
|114 |Delete Wifi Config Failed |
|116 |Missing or incorrect Wifi Profile Name |
|117 |Missing IEEE 802.1x Configuration |

#### (150-199) Maintenance Errors

|Error Code| Message |
|----------|-----------------------------------------|
|150 |Clock sync failed |
|151 |Hostname sync failed |
|152 |Network sync failed |
|150 |Clock synchronization failed |
|151 |Hostname synchronization failed |
|152 |IP synchronization failed |
|153 |Change Password failed |
24 changes: 6 additions & 18 deletions docs/Reference/architectureOverview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,27 +116,15 @@ Each microservice has an associated log file which can contain helpful debug inf

1. Open a Terminal or Powershell/Command Prompt and run the command to list the containers:

=== "Linux"
```
sudo docker ps
```

=== "Windows (Powershell)"
```
docker ps
```
```
docker ps
```

2. Copy the first three digits of the container ID of interest. Run the docker logs command followed by the container ID:

=== "Linux"
```
sudo docker logs <container ID>
```

=== "Windows (Powershell)"
```
docker logs <container ID>
```
```
docker logs <container ID>
```

See more help options for the `docker logs` command in [Docker Documentation](https://docs.docker.com/engine/reference/commandline/logs/).

Expand Down
11 changes: 3 additions & 8 deletions docs/Reference/middlewareExtensibility.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,13 +61,8 @@ After implementing the multitenancy code changes and starting the services, prof

Then when activating and configuring the AMT device using RPC, provide the `-tenant` flag with the `tenantID` of the profile. [Find all RPC flags in the RPC CLI docs](./RPC/commandsRPC.md). See example command below.

=== "Linux"
``` bash
sudo ./rpc activate -u wss://server/activate -n -profile profilename -tenant profileTenantID
```
=== "Windows"
```
.\rpc activate -u wss://server/activate -n -profile profilename -tenant profileTenantID
```
```
rpc activate -u wss://server/activate -n -profile profilename -tenant profileTenantID
```

<br>
Loading

0 comments on commit 3e82c99

Please sign in to comment.