C H A P T E R 5 |
Command-Line Interface |
The command-line interface (CLI) for the Sun Fire B10p SSL proxy blade is used for viewing and configuring information and statistics. The interface is accessible by using the console command from the Sun Fire B1600 service controller command-line (sc>). See the Sun Fire B1600 Blade System Chassis Software Setup Guide section 1.5 for details on connecting to the service controller. This provides a good framework to present all commands and their relationship to each other. In Appendix G, the commands are listed alphabetically.
This chapter contains the following sections:
Commands are organized by function using a hierarchy of menus. Each menu supports its own set of commands, prompt, and help messages. The main (root) menu is the first menu accessible to the operator. Depending on the operator's access level different menus and commands are available and displayed.
Parameters to commands can be entered directly on the command line or be entered by the operator when prompted for the input. Some commands do not accept command-line parameters and will prompt for all input (for example, set management). Default values for prompts are set whenever possible and can be entered by hitting the Return or Enter key. The "." character can be used to cancel the current command.
Operator-specified names must be 32 characters or less, alphanumeric, and may contain spaces.
The command-line interface supports features such as automatic command completion, history, context-sensitive help, and other editing commands and shortcuts. For example, the command to create a key can be entered as either create key or cr k (or by as few characters as necessary to avoid conflict). The logout and shutdown commands must be entered in full to avoid conflict with the log and the sh shortcut for the show command.
The following two command sequences are equivalent.
Note - Enter ? or help to see a list of available commands and context-sensitive help. |
Users must first log on to the command interface before access to any commands is allowed.
The SSL proxy blade supports three access levels for initialization and configuration purposes. The three levels are: User, Administrator, and Security Officer, each with its own password. The privileges for each access level are described in the table below.
Can only display certain system information. Cannot change any system information or state of the SSL proxy blade. |
||
admin |
Perform network administration. |
|
so |
The following command descriptions include the required access levels (User, Administrator, or Security Officer) for each command. Commands are not accessible if the access level of the command is higher than the access level of the logged in user.
Concurrent access to the SSL proxy blade is supported. Multiple users of any type can access the SSL proxy blade at a given time. This includes any combination of Telnet or console. The who and write commands arrange single Security Officer or Administrator access during delicate configuration tasks.
The CLI enables operators to log on, log off, change operator password, and write to other users who are currently logged on.
A message sent to multiple users with the same login is delivered to only one of them. |
All commands are typed at the CLI# prompt.
For example, for the who command:
Following is an example using the write command:
The following commands can be entered from within any menu.
Following are examples of the global commands listed in TABLE 5-4.
The show ntp command returns output similar to the following:
As so or admin, type the set ntp, command.:
CLI# set ntp Enter NTP server IP address (192.168.1.5): Enter NTP port (123): Enter NTP enable/disable (enable): NTP synchronization enabled. 2002-04-02 23:22:01 UTC |
The show config command provides a great deal of system information. It returns output similar to the following:
The SSL proxy blade can be in one of several different operating states: Un-initialized, Stopped, Started, and Fault. During normal operating conditions the SSL proxy blade will be in one of two main states:
During error or fault conditions, the SSL proxy blade will be in one of two secondary states:
No secure content (for example, no keys), state after tamper detection. |
|
TABLE 5-5 describes the system state commands:
Most commands can be used while the SSL proxy blade is processing traffic. Some commands require the system to be stopped before they can be performed. Configuration changes, like software upgrades and feature installation, cannot be made while the SSL proxy blade is processing SSL traffic and require reboot after completion.
TABLE 5-6 lists the commands that require the SSL proxy blade to be stopped or rebooted or both. If the command cannot be executed in the current SSL proxy blade state, the CLI will display a message and tell you to reboot when completed.
When the SSL proxy blade detects an unrecoverable problem, it goes to a limited functionality fault state. The fault state allows some commands for diagnostics purposes.
The SSL proxy blade has two traffic ports dedicated to processing SSL traffic for the servers. Both ports use the same TCP port number for encrypted traffic, typically 443, and the same TCP port number for clear text, for example, 880.
There are commands available for port numbers, enabling traffic ports, and setting network interface parameters for duplex, speed, and flow control.
In the context of TCP/IP protocol specifications, the TCP port numbers below 1024 are reserved for TCP services. Some numbers in this range are reserved for specific protocols, such as FTP (20,21), HTTP (80), HTTPS (443), while other numbers are available for new services (see TABLE 5-7). The port numbers 1024 and above are used by clients, which typically assign them sequentially to new TCP connections.
Currently, the SSL proxy blade supports the HTTPS/HTTP protocol. In addition, the SSL proxy blade has been successfully used in lab settings with POP3S and IMAPS protocols.
The SSL proxy blade requires a secure TCP port number to listen to traffic from the clients, and a clear TCP port number to send traffic to the server. The secure port number is usually 443, the standard port number for HTTPS clients. The clear port must be an available TCP number below 1024.
In the SSL proxy blade, the secure and clear port numbers apply to all services.
External access, for example, from remote browsers or even local machines, can be prevented by combining one or more of the following techniques:
As any user, type the show portpair command:
CLI# show portpair portpair 1: secure port: 443 clear port: 880 portpair 2: secure port: 0 clear port: 0 portpair 3: secure port: 0 clear port: 0 portpair 4: secure port: 0 clear port: 0 |
Use the set portpair command to set the TCP port numbers used for processing secure and clear traffic.
Typical standard settings are:
These port numbers are used for all services.
As so or admin, type the set portpair command:
CLI# set portpair Enter portpair number (1..4) (1): Enter secure port (https) (443): Enter clear port (http) (880): config save & reboot to use activate portpair(s). CLI# |
Use the show httpsforward command to learn whether HTTPS forwarding is enabled or disabled.
As any user type the show httpsforward command:
Use the set httpsforward command to set the HTTPS forward function.
As so or admin, type set httpsforward command:
You can enable and configure each of the SSL proxy blade's two traffic ports with IP address and netmask. This allows the port to respond to ARP and ping requests and to be used for health check purposes. In addition, you can specify each port's network link and interface settings.
Use the show link command to display the current link settings for all traffic ports.
As any user, type the show link command:
Use the set link command to set the link availability for a specified port or for all ports. You can save the configuration to make it permanent to exist after power off. You can also disable the link, which turns off the interface until the link is enabled again.
Use the set link restart command to apply the link settings instead of rebooting the SSL proxy blade. If the blade is not stopped you will be prompted to stop it when you try to change the link settings.
As so or admin, type the set link command and the desired variable:
The following example enables all ports.
The SSL proxy blade has two network interfaces for traffic running at 1000 Mbps full duplex.
Use the show interface command to display the current interface settings for the two traffic ports. The configuration appears in parenthesis, the non-parenthesis is the negotiated setting. The port LEDs reflect the negotiated setting.
As any user, type the show interface command:
As any user, type the show routed command:
The SSL proxy blade stores all configuration information in encrypted form with a device-unique key. The SSL proxy blade stores a permanent configuration, which is read and decrypted when the device is powered on or rebooted with an operator command. All changes to the active configuration must be saved for the change to be made permanent.
The configuration can be exported and saved as a backup. The import command allows a configuration to be set from a backup. All backups are encrypted using a pass-phrase.
Except for the commands that only display information, most CLI# commands change the active configuration immediately. Be sure to save the configuration after changes are made. In addition, when logging out or performing a shut down you are prompted to save the configuration.
The config compare command displays any difference between the RAM configuration and the Active Configuration file. The config default command overwrites the permanent configuration stored in flash.
Following are descriptions of the configuration management commands.
Use the config compare command to display the differences between the current running configuration and the configuration saved as permanent in the flash memory.
As so or admin, type the config compare command.
If the configuration matches, you see the following output:
If the configuration does not match, you see the following output:
Use the config default command to reset the permanent configuration information to its initial default settings. All values are set to defaults. The resulting state is called uninitialized because there is no secure content.
As so or admin, type the config default command:
Use the config reset command to reset the active configuration with the permanent configuration.
Note - The config reset command overwrites any changes to the active configuration. You must stop all SSL processing before performing this command. |
As so or admin, type the config reset command:
CLI# config reset This will erase current configuration in memory Are you sure you want to do this (Yes/No)? |
Use the config save command to save the active configuration to flash. This overwrites the permanent configuration in flash. Use this command after you make changes to the active configuration.
As so or admin, type the config save command:
The SSL proxy blade allows the security officer to create encrypted backups of configurations. The import and export commands are used for this purpose. During the export command, the operator is prompted to enter a user defined pass-phrase that is used to encrypt the configuration. The pass-phrase must be re-entered when the configuration is imported. Configurations are encrypted and then imported or exported using PEM format.
Configurations may be imported from another SSL proxy blade. There are some restrictions regarding licenses for software features that are imposed when importing configurations from another SSL proxy blade. See the section on licensing for more information.
Only the security officer (so) can export and import configurations because the user pass -phrase must be entered to decrypt the configuration. The configuration is exported using TFTP or FTP. Copy and paste functions are not provided because the configuration can span many pages.
Use the export ftp config command to export the active configuration using FTP to copy the configuration to a remote computer.
As so, type the command export ftp config:
Use the export tftp config command to export the active configuration using TFTP to copy the configuration to a remote computer. Refer to Setting Up a TFTP Server for details on how to set up a TFTP server.
As so, type the command export tftp config:
The operator can import a configuration using FTP, TFTP, or by pasting the configuration into the CLI when prompted. It is also possible to perform a partial import, where only a specified section of a configuration is imported. The SSL proxy blade must be stopped before an import can be performed.
The import command will prompt the operator for the specific section to import. The choices are:
Import system configuration: Includes networks, logging, and settings |
|
Import SSL configuration: Includes certificates and services settings |
Use the import ftp config command to import a configuration using FTP and set it to the active configuration.
Note - The SSL proxy blade must be stopped before importing a configuration. |
As so, type the command import ftp config:
Use the import tftp config command to import a configuration using TFTP and set it to the active configuration. Refer to Setting Up a TFTP Server for details on how to setup a TFTP server.
Note - The SSL proxy blade must be stopped before importing a configuration. |
As so, type the command import tftp config:
The SSL proxy blade requires that keys and certificates be installed before SSL traffic can be processed. The SSL handshake requires a private key and signed certificate to be associated with each server. The certificate contains the public key and key issuer information, and is digitally signed by a recognized Certificate Authority (CA).
To create a valid certificate, a key and certificate signing request are created. The certificate request contains the public key, key issuer information, and other information. The key is then submitted to a certificate authority (such as Verisign) for signing. The signed certificate is then imported into the SSL proxy blade using the original key.
The SSL proxy blade can hold up to 1024 keys, which are identified by a key name. For each key, information including private keys and certificates are stored. The show keys command lists the available keys and their signing status. Other CLI commands are used to generate private/public key pairs, create signing requests for the CA, and import and export certificates and keys. See the Certificate Formats for information on certificate format compatibility.
Self-signing is used for testing or for intranet use. There are three basic operations associated with keys and certificates:
1. Create a private-public key pair.
CLI# create key Enter key name: keyname Enter key strength (1024): 512/1024/2048 Key keyname generated. |
2. Create a self-signed certificate from the new key pair.
3. Use show keys, or export certificate commands to see the resulting key and certificate.
This is the standard way to create a certificate that most browsers recognizes as valid. This method does not generate any errors or warnings for the user.
1. Create a private-public key pair.
CLI# create key Enter key name: keyname Enter key strength (1024): 512/1024/2048 Key keyname generated. |
2. Create a certificate signing request using the new key pair.
Observe the following restrictions when creating a certificate.
a. Enter the two-letter ISO code for the country.
b. To avoid client browser warnings the common name should be the same as the domain name for the web site that is requesting the certificate.
c. Do not use any of these characters: !, @, #, $, %, ^, *, (, ), \, /, ?, ~
d. Make sure the email address contains an at sign (@)
3. Use show keys, or export certrequest commands to see the resulting key and certificate.
4. Copy and paste the certificate request into a file.
You can also export the certificate request using ftp or tftp.
5. Send the certificate request file to the CA and receive a signed certificate.
See Appendix C for details.
6. Import the certificate received from the CA into the SSL proxy blade by using either import certificate command and cut and paste the certificate, or by using the import ftp/tftp certificate command.
When you install the SSL proxy blade, you might have an existing certificate in the server that you may want to load into the SSL proxy blade. Following are instructions to load an existing key and associated certificate from a server. The SSL proxy blade supports copy and paste as well as FTP and TFTP methods for import.
1. Import the private key (from a server, for example).
The SSL proxy blade supports the X.509 V3 standard certificate format used by most servers, and issued by recognized certificate authorities (for example, Verisign, Thawte, and others).
The X.509 format defines the data fields in the certificate. The PEM standard is commonly used to encode x.509 certificates for storage and transfer. PEM uses a character representation of text and binary data that is easy to handle for email, copy and paste, and other data transfer mechanisms. The SSL proxy blade supports importing and exporting of keys and certificates in PEM format.
Most Certificate Authorities provide PEM encoded certificates. Most servers provide facilities to export certificates and keys in PEM format. Private keys are often encrypted such that user must enter a pass-phase during export and import operations.
Note - You can set the default values for a certificate (country, state, and so on) by using the set defcert command. |
Use the show keys command to display the keys, the status (if a certificate or certificate signing request exists) and the number of services that are actively using the key.
As so or admin, enter the show keys command:
CLI# show keys Key Name Cert Use Count ============================================= key1024 cert|csr 1 key512 0 |
Use the create key command to create a new key with the specified name. A key is generated using the specified strength. The default strength is 1024 bits.
As so or admin, enter the create key command:
CLI# create key Enter key name: keyname Enter key strength (1024): 512/1024/2048 Key keyname generated. |
Use the delete key command delete the specified key and any certificates or certificate requests associated with the key.
Note - The key will not be deleted if it is currently in use by a service. |
1. As so, enter the delete key command:
2. Use the show keys command to see if the key has been deleted:
CLI# show keys Key Name Cert Use Count ============================================= key1024 cert|csr 1 key512 0 |
Use the import ftp key command to import a key using FTP.
As so, enter the import ftp key command:
Use the import tftp key command to import a key using TFTP.
As so, enter the import tftp key command:
CLI# import tftp key Enter key name: keyname Enter remote file name (key.pem): remote_filename Enter pass phrase (or enter): pass_phrase key imported. |
Use the import key command to import a key. Paste the key into the CLI and type a period (.).
1. As so, enter the import key command:
2. Paste the key into the CLI, then type a period.
Use the export ftp key command to export a key.
As so, enter the export ftp key command:
Use the export tftp key command to export a key using tftp.
As so, enter the export tftp key command:
CLI# export tftp key Enter key name: keyname Enter remote file name (key.pem): remote_filename Enter pass phrase: pass_phrase Re-enter pass phrase: pass_phrase Key exported. |
Use the export key command to export a key. The key is displayed in PEM format.
As so, enter the export key command:
Use the create certificate command to create a certificate for a specified key. The security officer is prompted for the information required to create a self-signed certificate. A self-signed certificate can be used for testing purposes.
Be sure to observe the following restrictions when creating a certificate:
As so, type the create certificate command:
Use the import ftp certificate command to set the certificate for an existing key.
As so, enter the import ftp certificate command:
Use the import tftp certificate command to set the certificate for an existing key.
As so, enter the import tftp certificate command:
Use the import certificate command to import a certificate for an existing key.
As so, enter the import certificate command:
Use the export ftp certificate command to export a certificate.
As so, enter the export ftp certificate command:
Use the export tftp certificate command to export a certificate.
As so, enter the export tftp certificate command:
CLI# export tftp certificate Enter key name: keyname Enter remote file name (cert.pem): remote_filename certificate exported. |
Use the export certificate command to export a certificate.
As so, enter the export certificate command:
Use the show defcert command to display the default settings used for creating certificates and signing requests.
As so or admin, enter the show defcert command:
Use the set defcert command to set the default certificate parameters used when creating certificates or signing requests.
As so, enter the set defcert command:
The security officer can create, export, or import a certificate signing request. The security officer is prompted for the information required to create the request. A signing request can be exported and sent to a recognized signing authority (CA) and then be imported back into the system.
Use the create certrequest command to create a certificate signing request (CSR).
As so, enter the create certrequest command:
Use the export ftp certrequest command to export a CSR using FTP.
As so, enter the export ftp certrequest command:
Use the export tftp certrequest command to export a CSR using TFTP.
As so, enter the export tftp certrequest command:
Use the export certrequest command to export a CSR using TFTP.
As so, enter the export certrequest command:
Services are used to represent each virtual IP (VIP) server and its associated IP address. The server IP should be a virtual IP with many load balanced servers. The SSL proxy blade can support up to 1024 services and services are stored in the configuration.
A service is associated with an existing certificate. Many services may be associated with the same certificate. The service also defines the level of cipher strength supported for secure connections.
When the SSL proxy blade receives encrypted data for an IP address, the associated service will be identified. The service determines the certificate and cipher strength to be used for SSL processing. If the service is not found, the SSL connection will not be accepted. No unassigned SSL traffic is allowed through the SSL proxy blade.
If DNS is enabled, the service name will be used as a DNS name. See DNS Name for a Service for details on DNS.
The Security Officer (so) or Administrator (admin) can create, delete, or show services.
Use the create service command to specify the servers that will have SSL processing. The service must specify a valid IP address and a valid key.
The available ciphers can be listed using the show cipher command.
As so or admin type the create service command:
Use the delete service command to delete the specified service.
Use the show service command to see if it is active or pending deletion.
As so or admin type the delete service command:
Use the show services command to display current services.
As so or admin type the show services command:
CLI# show services Service IP Address Key Cipher PortPair ================================================================ svc1 110.10.14.1 1024 best 443|880 |
Use the show config command to display the available ciphers.
As so or admin type the show config command.
If DNS is properly setup (set dns) and enabled, the service name is used as a DNS name to obtain the service IP address.
The service IP address has priority over DNS lookup. Thus, service IP must be 0.0.0.0 for DNS IP lookup to occur.
1. At the CLI# prompt, set DNS or make sure DNS is already enabled.
Use the show dns command to display the DNS server settings.
As so or admin type the show dns command:
CLI# show dns DNS IP address (primary): DNS_ip-addr DNS IP address (secondary): 0.0.0.0 Domain name: foo.com DNS service: enabled |
Use the set dns command to set the DNS server settings.
As any user, type the set dns command:
CLI# set dns Enter DNS IP address (primary) (192.168.101.1): Enter DNS IP address (secondary) (0.0.0.0): Enter domain name (foo.com): Enter DNS enable/disable (enabled): DNS enabled. |
The following commands are typically used for diagnostics. Additional informational commands, such as show boot, are described in TABLE 3-2.
As any user, enter the ping command:
Use the show serial command to display the serial port settings.
As any user, enter the show serial command:
Use the set lines command set the number of lines for the Telnet session.
Note - The typical number of lines on a Telnet terminal is 24. On terminals with small windows, or after windows resize, the display might request: Press any key to continue, to continue the output. |
Using a value of 0 sets an infinite number of lines.
With some indirect connections such as Expect scripts, the negotiation that tells the server how many lines is turned off. This command can be helpful in these cases.
As any user, enter the set lines command plus the number of lines:
The SSL proxy blade maintains global statistics that can accumulate for long periods. The reset stats commands clears the statistics. The per-service statistics are cleared every time the SSL proxy blade is rebooted.
Statistics provide information regarding system load, traffic mix, and some types of network errors.
The SSL proxy blade statistics are focused on SSL proxy blade performance and SSL related statistics. You can obtain additional statistics from the servers (for service related statistics) and from supporting network equipment, such as load balancers and switches, for network related statistics.
The following commands support the statistics functionality.
As so or admin, type the command show stats glob accum.
As so or admin, type the command show stats glob detail.
As so or admin, type the command show stats serv servicename.
As so or admin, type the command reset stats.
Note - Run the config save command after reset stats to save the changes. |
The SSL proxy blade logs messages (events) associated with various system and user activity. For diagnostic purposes it can also monitor traffic activity and exceptions. Each tracked event generates a log entry consisting of time stamp, category, and event description. There are many levels of logging, and the log destination(s) can be external or internal.
The SSL proxy blade provides five progressive levels of detail that determine the amount of information and quantity of events sent to each log destination. The set log command is used to set one of the following levels: off, alert, error, info, debug, from low to high amount of detail.
Displays only most important events (least amount of information). |
|
Each log level will log all events for the specified level and all lower log levels. Each log destination may have a different level.
Info level events track various management events such as login, logout, reboot, back up configuration and can be categorized as State, Access, and Config.
The following is an example of a log output:
Debug level events is reserved for diagnostic purposes. The debug level can effect performance and should be off during normal operation. At logout or reboot, you will be prompted if the log is set to debug.
The SSL proxy blade can log messages to any of four destinations at the same time:
Each destination method is described below.
Serial port logging displays messages on the blade console of the Sun Fire B1600 Blade.
syslog logging sends UDP-based messages to remote UNIX-based syslogd servers. Both the log level and log facility can be used to direct the log events to a unique file on the UNIX-based host.
On a UNIX host, add the following line in /etc/syslog.conf:
Note - On a UNIX host, syslogd must be restarted to read changes in /etc/syslog.conf. |
The permanent log is intended to keep limited information about important system events. It is limited to a circular file of 64KB and is permanent across reboots. The internal log can be retrieved with the export log command.
SSL proxy blade internal memory logging.
The internal memory log is intended to keep information about important system events. It is limited to a circular file of 1MB. The log is not preserved across reboots. The internal memory log can be retrieved with the export mem command.
The set log serial command sets serial port logging to the SSL proxy blade console.
The initial default and preferred setting is off. The serial off setting does not turn-off boot messages to the serial port.
As so or admin, set the serial port logging to the serial port:
The set log syslog command sets the remote UNIX syslog logging. The default and recommended setting is off.
As so or admin, set the remote UNIX syslog logging:
CLI# set log syslog level ip-addr facility Enter log level (off, alert, error, info, debug): Input syslog server IP Address (0.0.0.0): Enter facility (auth, user, local1,.. local6): |
The set log file command sets permanent logging to an internal file in flash memory. The initial default and recommended setting is off.
As so or admin, set the remote UNIX syslog logging:
The set log mem command sets permanent logging to an internal memory. The current release does not allow you to set mem and serial log at the same time.
The initial default and recommended setting is off.
As so or admin, set the permanent logging to an internal memory:
The show log command displays the current log settings.
As so or admin, display the current log settings:
CLI# show log serial: info syslog: error file: off Note: "file" refers to an internal file in flash memory. |
The export ftp log command exports the permanent log to a remote computer using FTP.
As so or admin, export the permanent log to a remote computer:
The export tftp log command exports the permanent log to a remote computer using TFTP.
Use this command when the permanent log in flash is one of the log targets. To set this up, use the set log file info command.
Commands such as start and stop create log entries.
When you have some entries, export tftp log will export the entries to an external file.
As so or admin, export the permanent log to a remote computer:
CLI# export tftp log Enter remote file name (file): remote_filename Enter remote IP Address: remote_ip-addr log exported. |
The export ftp mem command exports the permanent log to a remote computer using FTP.
As so or admin, export the internal memory log to a remote computer:
The export log command exports the permanent log kept to the serial port.
As so or admin, export the permanent log to the serial port:
Copyright © 2004, Sun Microsystems, Inc. All rights reserved.