Defender for IoT CLI users and access
This article provides an introduction to the Microsoft Defender for IoT command line interface (CLI). The CLI is a text-based user interface that allows you to access your OT sensors and the on-premises management console for advanced configuration, troubleshooting, and support.
To access the Defender for IoT CLI, you'll need access to the sensor or on-premises management console.
- For OT sensors or the on-premises management console, you'll need to sign in as a privileged user.
- For Enterprise IoT sensors, you can sign in as any user.
Caution
Only documented configuration parameters on the OT network sensor and on-premises management console are supported for customer configuration. Do not change any undocumented configuration parameters or system properties, as changes may cause unexpected behavior and system failures.
Removing packages from your sensor without Microsoft approval can cause unexpected results. All packages installed on the sensor are required for correct sensor functionality.
Privileged user access for OT monitoring
Use the admin user when using the Defender for IoT CLI, which is an administrative account with access to all CLI commands. On the on-premises management console, use the cyberx user.
If you're using a legacy software version, you may have one or more of the following users:
| Legacy scenario | Description |
|---|---|
| Sensor versions earlier than 23.2.0 | In sensor versions earlier than 23.2.0, the default admin user is named support. The support user is available and supported only on versions earlier than 23.2.0. Documentation refers to the admin user to match the latest version of the software. |
Other CLI users cannot be added.
For more information, see On-premises users and roles for OT monitoring with Defender for IoT.
Supported users by CLI actions
The following tables list the activities available by CLI and the privileged users supported for each activity. The cyberx and cyberx_host users are only supported in versions earlier than 23.1.x.
Appliance maintenance commands
| Service area | Users | Actions |
|---|---|---|
| Sensor health | admin, cyberx | Check OT monitoring services health |
| Reboot and shutdown | admin, cyberx, cyberx_host | Restart an appliance Shut down an appliance |
| Software versions | admin, cyberx | Show installed software version Update software version |
| Date and time | admin, cyberx, cyberx_host | Show current system date/time |
| NTP | admin, cyberx | Turn on NTP time sync Turn off NTP time sync |
Backup and restore commands
| Service area | Users | Actions |
|---|---|---|
| List backup files | admin, cyberx | List current backup files Start an immediate, unscheduled backup |
| Restore | admin, cyberx | Restore data from the most recent backup |
| Backup disk space | cyberx | Display backup disk space allocation |
Local user management commands
| Service area | Users | Actions |
|---|---|---|
| Password management | cyberx, cyberx_host | Change local user passwords |
| Sign-in configuration | cyberx | Define maximum number of failed sign-ins |
Network configuration commands
| Service area | Users | Actions |
|---|---|---|
| Network setting configuration | cyberx_host | Change networking configuration or reassign network interface roles |
| Network setting configuration | admin | Validate and show network interface configuration |
| Network connectivity | admin, cyberx | Check network connectivity from the OT sensor |
| Physical interfaces management | admin | Locate a physical port by blinking interface lights |
| Physical interfaces management | admin, cyberx | List connected physical interfaces |
Traffic capture filter commands
| Service area | Users | Actions |
|---|---|---|
| Capture filter management | admin, cyberx | Create a basic filter for all components Create an advanced filter for specific components List current capture filters for specific components Reset all capture filters |
Defender for IoT CLI access
To access the Defender for IoT CLI, sign in to your OT or Enterprise IoT sensor or your on-premises management console using a terminal emulator and SSH.
- On a Windows system, use PuTTY or another similar application.
- On a Mac system, use Terminal.
- On a virtual appliance, access the CLI via SSH, the vSphere client, or Hyper-V Manager. Connect to the virtual appliance's management interface IP address via port 22.
Each CLI command on an OT network sensor or on-premises management console is supported a different set of privileged users, as noted in the relevant CLI descriptions. Make sure you sign in as the user required for the command you want to run. For more information, see Privileged user access for OT monitoring.
Access the system root as an admin user
When signing in as the admin user, run the following command to access the host machine as the root user. Access the host machine as the root user enables you to run CLI commands that aren't available to the admin user.
Run:
system shell
Sign out of the CLI
Make sure to properly sign out of the CLI when you're done using it. You're automatically signed out after an inactive period of 300 seconds.
To sign out manually on an OT sensor or on-premises management console, run one of the following commands:
| User | Command |
|---|---|
| admin | logout |
| cyberx | cyberx-xsense-logout |
| cyberx_host | logout |
Next steps
You can also control and monitor your cloud connected sensors from the Defender for IoT Sites and sensors page. For more information, see Manage sensors with Defender for IoT in the Azure portal.