Get FDA readyServicesHelm help

Provision devices using command line

Overview

Use the mcguard_provision utility to generate and upload provisioning requests for testing or when devices cannot use Guardian Library. The command line tool supports both connected and disconnected provisioning workflows, as well as proxy provisioning setups.

When to use mcguard_provision:

  • Testing provisioning workflows

  • Devices that cannot integrate Guardian Library

  • Advanced troubleshooting scenarios

  • Proxy provisioning setups where a gateway device handles provisioning for other devices

Additional prerequisites

Make sure that you also have the general provisioning prereqs before beginning provisioning. To use the command line, you'll also need these prereqs:

  • mcguard_provision utility installed

  • Device information readily available (component name, system ID, hardware ID)

  • For proxy provisioning only: Proxy device must be provisioned as a fully online component first.

Technical requirements

Platform compatibility

  • Linux/BSD hosts: Commands are formatted for Linux/BSD hosts.

  • Windows hosts:

    • Add .exe to the executable name

    • Switchpaths from / to \ notation

File organization

All command line utilities use a working directory approach. For example, during Connected initial provisioning, the mcguard_provision utility expects to see a .mcts, .mcpip and .mcpp file in the working directory.

  • All source profile files (.mcts, .mcpi, .mcpip, .mcp, .mcpp) should appear in the same folder as the provided profile path.

  • Any mcguard_provision CLI outputs are saved to the same working directory.

Network configuration

  • Use default Guardian Cloud endpoints unless Medcrypt specifies a different IP address override for you

  • Use default timeout settings unless Medcrypt directs you to modify timeout configurations

  • Both of these are controlled in the provisioningOptions , but should only be modified as directed by Medcrypt.

Example parameters

The following example values are used throughout the command examples in this documentation:

  • Provisioning component: my_component

  • Provisioning host: 35.164.222.194:19109

  • Provisioning system: my_system

  • Provisioning hardware ID: my_hid

  • Proxy component: my_proxy

  • Proxy system: my_proxy_system

  • Proxy hardware ID: my_proxy_hid

Replace these with your actual device and system information.

Connected device provisioning

Use this method for devices with network connectivity that can communicate directly with Guardian Cloud. Refer to Guardian file types for more details on file types and extensions.

Initial provisioning

  1. Run this command to generate the provision request (.mcpr file) and private identity (.mcpi file) in your working directory, automatically submit them to Guardian Cloud, then automatically retrieve the certified profile (.mcp file) to the device. The device will be fully provisioned when the command completes successfully.

# Syntax
./mcguard_provision --mode provision --component <component_name> --system <system_name> --hardware-id <hardware_id> --ip-address <guardian_host:port> <path_to_initial_provisioning_profile>

# Example
./mcguard_provision --mode provision --component my_component --system my_system --hardware-id my_hid --ip-address 35.164.222.194:19109 /home/user/guardian/profiles/initial_profile

Reprovisioning

  1. Run this command to generate a new provision request using your existing private identity, automatically submit it to Guardian Cloud, and retrieve the updated certified profile. The device will be reprovisioned when the command completes successfully.

# Syntax
./mcguard_provision --mode reprovision --component <component_name> --system <system_name> --hardware-id <hardware_id> --ip-address <guardian_host:port> --reprovision <path_to_provisioned_profile>

# Example
./mcguard_provision --mode reprovision --component my_component --system my_system --hardware-id my_hid --ip-address 35.164.222.194:19109 --reprovision /home/user/guardian/profiles/provisioned_profile

Disconnected device provisioning

Use this method for devices without network connectivity where provisioning requests must be manually transferred to Guardian Cloud.

Initial provisioning

  1. Run this command to generate the provision request (.mcpr file) and private identity (.mcpi file) in your working directory. 

# Syntax
./mcguard_provision --mode provision --component <component_name> --system <system_name> --hardware-id <hardware_id> --offline <path_to_initial_provisioning_profile>

# Example
./mcguard_provision --mode provision --component my_component --system my_system --hardware-id my_hid --offline /home/user/guardian/profiles/initial_profile

  1. Upload provision request: Manually upload the .mcpr file to the Guardian Cloud UI.

  2. Download certified profile: Once processed, download the .mcp file from the Guardian Cloud UI.

  3. Install on device: Transfer the .mcp file to the device where the .mcpi file is located to complete provisioning.

Reprovisioning

  1. Run this command to generate a new provision request (.mcpr file) using your existing private identity (.mcpi file). 

# Syntax
./mcguard_provision --mode reprovision --component <component_name> --system <system_name> --hardware-id <hardware_id> --offline <path_to_provisioned_profile>

# Example
./mcguard_provision --mode reprovision --component my_component --system my_system --hardware-id my_hid --offline /home/user/guardian/profiles/provisioned_profile

  1. Upload provision request: Manually upload the .mcpr file to the Guardian Cloud UI.

  2. Download certified profile: Once processed, download the .mcp file from the Guardian Cloud UI.

  3. Install on device: Transfer the .mcp file to the device where the .mcpi file is located to complete reprovisioning.

Proxy device provisioning

Proxy setup requirements:

  • The proxy device must be provisioned as a fully online component before it can upload other devices' provisioning requests.

  • The disconnected device's .mcpr file must be transferred to the proxy device first

  • When uploading using a proxy device, use the proxy device's component and hardware ID, NOT the device that created the provisioning request.

  1. Run this command to provision the proxy device. The proxy will generate its provision request (.mcpr) and private identity (.mcpi), automatically submit to Guardian Cloud, and automatically retrieve its certified profile. Once complete, the proxy device can handle provisioning requests for other devices.

# Syntax
./mcguard_provision --mode provision --component <proxy_component> --system <proxy_system> --hardware-id <proxy_hardware_id> --ip-address <guardian_host:port> <path_to_proxy_provisioning_profile>

# Example
./mcguard_provision --mode provision --component my_proxy --system my_proxy_system --hardware-id my_proxy_hid --ip-address 35.164.222.194:19109 /home/user/guardian/proxy/provisioning_profile

2. Upload the provisioning request via proxy:

  1. Run this command to submit a disconnected device's provision request through the proxy device. The proxy will automatically upload the .mcpr file to Guardian Cloud and retrieve the certified profile (.mcp file).

# Syntax
./mcguard_provision --mode upload --component <proxy_component> --hardware-id <proxy_hardware_id> --ip-address <guardian_host:port> --provision-request <path_to_disconnected_device_pr> --output-profile <path_to_output_certified_profile> <path_to_provisioned_proxy_profile>

# Example
./mcguard_provision --mode upload --component my_proxy --hardware-id my_proxy_hid --ip-address 35.164.222.194:19109 --provision-request /home/user/device_requests/device_pr.mcpr --output-profile /home/user/certificates/device_cp.mcp /home/user/guardian/proxy/provisioned_profile

2. Transfer to the certified profile to the disconnected device.

Parameter reference

Each of these parameters precedes the actual value of the object except --offline.

Required parameters:

  • --mode: Used during provisioning, reprovisioning, or uploading provisioning request.

  • --component: Component name/identifier

  • --system: System name identifier. This is also known as the system definition.

  • --hardware-id: Unique hardware identifier (typically a device serial number).

Connected only:

  • --ip-address: Guardian Cloud endpoint (host:port)

Disconnected only:

  • --offline: Enable offline/disconnected mode

Reprovisioning only:

  • --reprovision: Specify path to existing provisioned profile (.mcp file)

Proxy only:

  • --provision-request: Specify path to provision request (.mcpr file) for proxy upload

Proxy file naming recommendation

When handling files during proxy provisioning, you can name them however you prefer. We recommend:

  • Preserving file extensions (.mcpr for provision requests, .mcp for certified profiles) for easy identification by your team and Medcrypt

  • Using descriptive names that identify the device or component

  • Including version numbers or dates if managing multiple provisioning attempts

Troubleshooting for command line

Network connectivity issues

Error: Cannot connect to provisioning endpoints

  1. Review Guardian log output or increase log level to identify warnings or errors.

  2. Test network connectivity to provisioning endpoints using tools like telnet or netcat.

# Syntax
telnet <guardian_host> <port>

# Example
telnet 35.164.222.194 19109

  1. Check firewall configuration and ensure the Guardian Cloud endpoint is accessible

  2. Verify the IP address and port are correct

  3. Sign in to Guardian Cloud to review device provisioning reports.

  4. Check whether your system definition is configured for automatic or manual approval.

Prevention

  • Ensure stable network connectivity and proper firewall configuration

  • Configure proper firewall rules for Guardian Cloud endpoints

  • Test connectivity in your network environment before deployment

Status Shutdown(
    const bool & in_force =false
)

Command execution issues

File not found errors:

  • Verify all required profile files (.mcts, .mcpip, .mcpp) are in the specified directory

  • Check file permissions and ensure the utility can read the profile files

  • Confirm the profile path is correct and accessible

Invalid parameter errors:

  • Verify component name, system name, and hardware ID match your Guardian Cloud configuration

  • Check that hardware ID follows character limitations (typically 36 characters max)

  • Ensure IP address format is correct (host:port)

Proxy provisioning issues

Make sure that you have met the proxy setup requirements.

Proxy device not accepted:

  • Confirm the proxy device is fully provisioned and operational. This must be done before the proxy device can be used to provision other devices.

  • Verify you're using the proxy device's component and hardware ID, not the target device's.

  • Check that the proxy device's profile allows proxy operations.

File transfer issues:

  • Ensure the provision request (.mcpr file) from the disconnected device is accessible to the proxy device.

  • Verify file integrity during manual transfer processes.

  • Check file permissions allow the proxy device to read the provision request.

Debugging and logging

Guardian does not create log files. Instead, logging is controlled by the application:

  • Guardian logs to stdout and stderr, which appear in the terminal/CLI of the running application during execution. Look for specific error codes or connection failures in the output.

  • Custom logging: Use SetLoggingCallback to redirect log messages to a callback function, stopping terminal output and allowing custom log handling

  • Log control: Applications can control log level and verbosity.

  • Guardian Cloud UI: Check the Guardian Cloud interface for additional error details and provisioning status.

PreviousProvision devices using APINextDevice provisioning code examples

Last updated

Was this helpful?