Command Line Interface: The Basics

This chapter contains the following sections:

Accessing the Command Line Interface (CLI)

The Command Line Interface is accessible via SSH or Telnet on IP interfaces that have been configured with these services enabled, or via terminal emulation software on the serial port. By factory default, SSH and Telnet are configured on the Management port. Use the interfaceconfig command to disable these services.

Access to the CLI varies depending on the management connection method chosen while setting up the appliance. The factory default username and passphrase are listed next. Initially, only the admin user account has access to the CLI. You can add other users with differing levels of permission after you have accessed the command line interface for the first time via the admin account. The system setup wizard asks you to change the passphrase for the admin account. The passphrase for the admin account can also be reset directly at any time using the passphrase command.

To connect via Ethernet: Start an SSH or Telnet session with the factory default IP address 192.168.42.42. SSH is configured to use port 22. Telnet is configured to use port 23. Enter the username and passphrase below.

To connect via a Serial connection: Start a terminal session with the communication port on your personal computer that the serial cable is connected to. See the “Setup and Installation” chapter for more information. Enter the username and passphrase below.

Log in to the appliance by entering the username and passphrase below.

Factory Default Username and Passphrase

  • Username: admin
  • Passphrase: ironport

For example: 

login: admin

passphrase: ironport

Command Line Interface Conventions

This section describes the rules and conventions of the AsyncOS CLI.

Command Prompt

The top-level command prompt consists of the fully qualified hostname, followed by the greater than ( > ) symbol, followed by a space. For example: 


mail3.example.com>

If the appliance has been configured as part of a cluster with the Centralized Management feature, the prompt in the CLI changes to indicate the current mode. For example: 


(Cluster Americas) >

or 


(Machine los_angeles.example.com) >

See “Centralized Management” in the user guide for more information.

When running commands, the CLI requires input from you. When the CLI is expecting input from you, the command prompt shows the default input enclosed in square brackets ( [] ) followed by the greater than ( > ) symbol. When there is no default input, the command prompt brackets are empty.

For example: 


Please create a fully-qualified hostname for this Gateway
(Ex: "mail3.example.com"):
[]> 
mail3.example.com

When there is a default setting, the setting is displayed within the command prompt brackets. For example: 


Ethernet interface:
1. Data 1
2. Data 2
3. Management
[1]> 1

When a default setting is shown, typing Return is equivalent to typing the default: 


Ethernet interface:
1. Data 1
2. Data 2
3. Management
[1]> (type Return)

Command Syntax

When operating in the interactive mode, the CLI command syntax consists of single commands with no white spaces and no arguments or parameters. For example: 


mail3.example.com> systemsetup

Select Lists

When you are presented with multiple choices for input, some commands use numbered lists. Enter the number of the selection at the prompt.

For example: 


Log level:
1. Error
2. Warning
3. Information
4. Debug
5. Trace
[3]> 3

Yes/No Queries

When given a yes or no option, the question is posed with a default in brackets. You may answer Y, N, Yes, or No. Case is not significant.

For example: 


Do you want to enable FTP on this interface?  [Y]> n

Subcommands

Some commands give you the opportunity to use subcommands. Subcommands include directives such as NEW , EDIT , and DELETE . For the EDIT and DELETE functions, these commands provide a list of the records previously configured in the system.

For example: 


mail3.example.com> interfaceconfig
Currently configured interfaces:
1. Management (192.168.42.42/24: mail3.example.com)
Choose the operation you want to perform:
- NEW - Create a new interface.
- EDIT - Modify an interface.
- GROUPS - Define interface groups.
- DELETE - Remove an interface.
[]>

Within subcommands, typing Enter or Return at an empty prompt returns you to the main command.

Escape

You can use the Control-C keyboard shortcut at any time within a subcommand to immediately exit return to the top level of the CLI.

History

The CLI keeps a history of all commands you type during a session. Use the Up and Down arrow keys on your keyboard, or the Control-P and Control-N key combinations, to scroll through a running list of the recently-used commands. 


mail3.example.com> (type the Up arrow key)


mail3.example.com> interfaceconfig (type the Up arrow key)


mail3.example.com> topin (type the Down arrow key)

Command Completion

The command-line interface supports command completion. You can type the first few letters of some commands followed by the Tab key, and the CLI completes the string for unique commands. If the letters you entered are not unique among commands, the CLI “narrows” the set. For example: 

mail3.example.com> set (type the Tab key)
setgateway, sethostname, settime, settz
mail3.example.com> seth 
(typing the Tab again completes the entry with sethostname)

For both the history and file completion features of the CLI, you must type Enter or Return to invoke the command.

Configuration Changes

You can make configuration changes while email operations proceed normally.

Configuration changes will not take effect until you complete the following steps:

Procedure

Step 1

Issue the commit command at the command prompt.

Step 2

Give the commit command the input required.

Step 3

Receive confirmation of the commit procedure at the CLI.

What to do next

Changes to configuration that have not been committed will be recorded but not put into effect until the commit command is run.


Note
Not all commands require the commit command to be run. See CLI Quick Reference Guide for a summary of commands that require commit to be run before their changes take effect.

Exiting the CLI session, system shutdown, reboot, failure, or issuing the clear command clears changes that have not yet been committed.

General Purpose CLI Commands

This section describes the commands used to commit or clear changes, to get help, and to quit the command-line interface.

Committing Configuration Changes

The commit command is critical to saving configuration changes to the appliance. Many configuration changes are not effective until you enter the commit command. (A few commands do not require you to use the commit command for changes to take effect. The commit command applies configuration changes made since the last commit command or the last clear command was issued. You may include comments up to 255 characters. Changes are not verified as committed until you receive confirmation along with a timestamp.

Entering comments after the commit command is optional. 


mail3.example.com> commit
Please enter some comments describing your changes:
[]> Changed "psinet" IP Interface to a different IP address
Do you want to save the current configuration for rollback? [Y]> n
Changes committed: Fri May 23 11:42:12 2014 GMT

Note
To successfully commit changes, you must be at the top-level command prompt. Type Return at an empty prompt to move up one level in the command line hierarchy.

Clearing Configuration Changes

The clear command clears any configuration changes made since the last commit or clear command was issued. 


mail3.example.com> clear
Are you sure you want to clear all changes since the last commit?  [Y]> y
Changes cleared: Mon Jan 01 12:00:01 2003
mail3.example.com>

Quitting the Command Line Interface Session

The quit command logs you out of the CLI application. Configuration changes that have not been committed are cleared. The quit command has no effect on email operations. Logout is logged into the log files. (Typing exit is the same as typing quit.) 


mail3.example.com> quit
Configuration changes entered but not committed.  Exiting will lose changes.
Type 'commit' at the command prompt to commit changes.
Are you sure you wish to exit?  [N]> Y

Seeking Help on the Command Line Interface

The help command lists all available CLI commands and gives a brief description of each command. The help command can be invoked by typing either help or a single question mark ( ? ) at the command prompt. 


mail3.example.com> help

Batch Commands

AsyncOS includes support for batch command formats that allow you to execute certain CLI commands using a new, single-line CLI format. This format reduces the number of inputs required to complete tasks and provides a mechanism allowing you to easily automate common configuration tasks. Batch commands also allow you to issue commands remotely using an SSH client. This enables you to easily script CLI commands and execute them on multiple appliances at one time.

Not all commands have a batch equivalent, but all batch commands can be executed as non-batch commands.

Batch command syntax is dependent on the specific command being used. Please see the appropriate CLI example in The Commands: Reference Examples for more information about syntax specific to that command.

Batch Command Example

In the following example, the sendergroup REDLIST is created. It is then associated with the policy THROTTLED, and then the sender ‘possible_spammer.com’ is added to the sender group.

To execute this action using the CLI: 

example.com> listenerconfig

Currently configured listeners:

1. IncomingMail (on Management, 192.168.42.42/24) SMTP TCP Port 25 Public

2. OutgoingMail (on Data 2, 192.168.40.42/24) SMTP TCP Port 25 Private

Choose the operation you want to perform:
- NEW - Create a new listener.
- EDIT - Modify a listener.
- DELETE - Remove a listener.
- SETUP - Change global settings.

[]> edit

Enter the name or number of the listener you wish to edit.
[]> IncomingMail

Choose the operation you want to perform:
- NAME - Change the name of the listener.
- INTERFACE - Change the interface.
- LIMITS - Change the injection limits.
- SETUP - Configure general options.
- HOSTACCESS - Modify the Host Access Table.
- RCPTACCESS - Modify the Recipient Access Table.
- BOUNCECONFIG - Choose the bounce profile to use for messages injected on this listener.
- MASQUERADE - Configure the Domain Masquerading Table.
- DOMAINMAP - Configure domain mappings.

[]> HOSTACCESS

There are currently 4 policies defined.
There are currently 5 sender groups.

Choose the operation you want to perform:

- NEW - Create a new entry.
- EDIT - Modify an entry.
- DELETE - Remove an entry.
- MOVE - Move an entry.
- DEFAULT - Set the defaults.
- PRINT - Display the table.
- IMPORT - Import a table from a file.
- EXPORT - Export the table to a file.
- CLEAR - Remove all entries.

[]> NEW

1. New Sender Group
2. New Policy

[1]> 1

Enter a name for this sender group. (optional)

[]> REDLIST

Enter the hosts to add. CIDR addresses such as 10.1.1.0/24 are allowed.
IP address ranges such as 10.1.1.10-20 are allowed. IP subnets such as
10.2.3. are allowed.

Hostnames such as crm.example.com are allowed.

Partial hostnames such as .example.com are allowed.

Ranges of SenderBase Reputation scores such as SBRS[7.5:10.0] are
allowed.

SenderBase Network Owner IDs such as SBO:12345 are allowed.
Remote blacklist queries such as dnslist[query.blacklist.example] are
allowed.

Separate multiple hosts with commas

[]> possible_spammer.com

Select a behavior for this entry.

1. Accept
2. Relay
3. Reject
4. TCP Refuse
5. Continue
6. Policy: ACCEPTED
7. Policy: BLOCKED
8. Policy: THROTTLED
9. Policy: TRUSTED

[1]> 8

Enter a comment for this sender group.
[]>

There are currently 4 policies defined.
There are currently 6 sender groups.

To perform the same action using a CLI batch command: 

example.com> listenerconfig edit IncomingMail hostaccess new sendergroup 
REDLIST possible_spammer.com Policy: “THROTTLED”