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 either the support or 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. |
| Sensor software versions earlier than 23.1.x | In sensor software versions earlier than 23.1.x, the cyberx and cyberx_host privileged users are also in use. In newly installed versions 23.1.x and higher, the cyberx and cyberx_host users are available, but not enabled by default. To enable these extra privileged users, such as to use the Defender for IoT CLI, change their passwords. For more information, see Recover privileged access to a sensor. |
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 |
| Restart 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 |
|---|---|---|
| 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 |
TLS/SSL certificate commands
| Service area | Users | Actions |
|---|---|---|
| Certificate management | cyberx | Import TLS/SSL certificates to your OT sensor Restore the default self-signed certificate |
Local user management commands
| Service area | Users | Actions |
|---|---|---|
| Password management | cyberx, cyberx_host | Change local user passwords |
| Sign-in configuration | admin, cyberx, cyberx_host | Control user session timeouts |
| 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 |
| Network connectivity | cyberx | Check network interface current load Check internet connection |
| Network bandwidth limit | cyberx | Set bandwidth limit for the management network interface |
| 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 |
Alert commands
| Service area | Users | Actions |
|---|---|---|
| Alert functionality testing | cyberx | Trigger a test alert |
| Alert exclusion rules | admin, cyberx | Show current alert exclusion rules Create a new alert exclusion rule Modify an alert exclusion rule Delete an alert exclusion rule |
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
OT sensor versions earlier than 23.2.0 include the support privileged user instead of the admin user. If you're using an older version of the sensor software, any commands that are listed as supported for the admin user are also supported for the legacy support user.
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.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for