Option 5 - Use Restricted Shell

This section describes option 5 (Use Restricted Shell) from the Gateway System Settings option in the main menu.
gateway94
This section describes option
5
(Use Restricted Shell) from the Gateway System Settings option in the
API Gateway
main menu.
Use this option to quickly view or update system settings that were previously configured using options 1-4. The Restricted Shell lets you enter commands to rapidly update one or more system setting, without using the configuration wizards and without needing to log in as the 
root
 user.
The Restricted Shell differs from the Privileged Shell, which is used to run Linux commands that require root access.
Features of the Restricted Shell
The restricted shell provides the following features:
Tab Completion
You can press the [Tab] key after typing a few characters of a command and the restricted shell will attempt to complete the command for you. This is useful if you do not remember the exact name of the command. Pressing [Tab] with no command typed will list all the available commands. Pressing [Tab] within a sub-shell will complete arguments and options for the command, if available.
Sub-Shell
The restricted shell features a sub-shell that further restricts commands to only those valid for the selected sub-shell. For example, switching to the "service" sub-shell will only accept service-related sub-shell commands, and it will display the relevant sub-shell commands when [Tab] is pressed (for example, "disable", "enable", etc.).
To switch to a sub-shell, enter its name in the restricted shell, and then enter one or more commands for that sub-shell.
To execute a command for a sub-shell immediately, use the syntax:
<sub-shell>:<command>
For example, enter "banner:show" to display the current banner message.
The prompt will be updated to display the sub-shell in effect; for example:
Where:
  • "ssgconfig" is the name of the logged-in user
  • "fst" means "Foundation Services"
  • "<sub>" is the name of the sub-shell
Commands History
To view the commands previously executed, press the [Up] or [Down] arrow keys. You can also use the 
history
 command to view all the available command history. Note that all commands executed, whether successful or not, are listed.
Use a shortcut method to re-run a command from the history list. Enter !<number>, where "<number>" is the number of the command in the history list. For example, entering "!499" will reissue the command at 499.
Help for Commands
Every command in the restricted shell supports the help option:
--help
Use this option at any time to see more information about a command.
When you receive an error running a command, simply append --help
to suppress the error and see a help message; you do not need to enter the help options on its own.
Understanding the Parameters
In the command syntax, parameters enclosed within square brackets ("[ ]") are optional. For commands with [options], the options that must be specified are indicated as "(Required)" in the descriptions.
The syntax for the commands is in the following format:
[subshell]:command [options] param1 [param2]
Where:
  • [subshell]
     is the name of the subshell in which the command resides. For example, the Revision Manager commands are in subshell "revision".
  • command
     is the name of the command
  • [options]
     are one or more options that you can specify to modify the behavior of the command. Options that 
    must
     be specified are indicated with 
    "(Required)"
     in the description. Not all commands have options.
    Options are indicated either with a single dash (‘-‘) or a double dash (‘--‘). The single dash is the short form of the option (single character), while the double dash is the verbose version. An option is specified in different ways, depending on the context.
    For example, to set the timeout period for RADIUS authentication, you would use the command:
auth-radius:update --timeout=30
However to remove the timeout value, you would use this syntax:
auth-radius:delete --timeout
Options that require a value can be specified in a number of ways, for example these are all valid:
network:update --enableIpv6=true network:update --enableIpv6=yes network:update --enableIpv6 true network:update --enableIpv6 yes
  • param1
     indicates a required parameter
  • [param2]
     indicates an optional parameter
Use ‘\’ to escape spaces.
Running Restricted Shell Commands
To run restricted shell commands:
  1. Choose option 
    (Use restricted shell) from the Gateway main menu.
    The restricted shell opens, displaying the CA branding and some system information.
  2. Enter a command for the system setting to configure. Some tips:
    • To see a list of all available commands, press the [Tab] key
    • To view a detailed description of any command, enter:
[shell]
:
[command] 
- -help
The “[shell]” portion may be omitted. For example:
        shell:grep --help
        grep --help
Do not manually edit any Gateway configuration file, as any changes made will be lost once a Restricted Shell command is executed.
 For security, use of the backtick character (`) is disabled in these commands when using the restricted shell: CAT, HEAD, and TAIL.
Basic Commands
All basic accessed from the 
shell
 sub-shell.
Commands for the Revision Manager
The Revision Manager automatically tracks the changes made to the Gateway configuration, which is stored in the following directory:
l7-config/local
Revision Manager commands are accessed from the 
revision
 sub-shell.
Commands for System Configuration
Use the System Configuration commands to manage the following components:
  • System Time
     (stored in 
    /etc/ntp.conf, /etc/sysconfig/clock
    )
  • Keyboard Settings
     (stored in 
    /etc/sysconfig/keyboard
    )
  • Banner Message
     (stored in 
    /etc/motd
    )
All changes are tracked by the Revision Manager.
System Configuration commands are divided across their own sub-shells:
timezonekeyboardbanner
Commands for Network Configuration
Use the Network Configuration commands to manage the following components:
  • Host Settings 
    (stored in 
    /etc/hosts
    )
  • DNS Settings
     (stored in 
    /etc/dhcp/dhclient.conf, /etc/resolv.conf
    )
  • General Network Settings
     (stored in 
    /etc/sysconfig/network
    )
  • Network Interfaces
     (stored in 
    /etc/sysconfig/network-scripts/ifcfg-{xxx}
    , where ‘xxx’ is the interface name)
  • Static Routes
     (stored in 
    /etc/sysconfig/network-scripts/route-{xxx}
    , where ‘xxx’ is the interface name)
All changes are tracked by the Revision Manager.
Network Configuration commands are divided across their own sub-shells:
hostdnsnetworkinterfaceroute
Commands for Authentication Configuration
Use the Authentication Configuration commands to configure the authentication method for users on the machine. These commands update the following system files:
/etc/openldap/ldap.conf
/etc/nslcd.conf
/etc/nsswitch.conf
/etc/pam_ldap.conf
/etc/pam_radius.conf
/etc/pam.d/sshd
/etc/pam.d/login
/etc/sysconfig/authconfig
Note that 
/etc/sudoers
 will also be updated if LDAP or LDAP_RADIUS is selected and a group ID is entered.
All changes are tracked by the Revision Manager.
Authentication Configuration commands are divided across their own sub-shells:
authentication
auth-radius
 (for RADIUS method only)
auth-ldap
 (for LDAP or LDAP-RADIUS methods only)
When authenticating using RADIUS and/or LDAP, authentication will fall back to local authentication if communication with RADIUS or LDAP is not possible or if authentication fails. 
Commands for Restricted Services
The Restricted Service feature is used to manage the 
initd
 and 
upstart
 services.
All Restricted Service commands are accessed from the 
service
 sub-shell.
Commands for Import/Export Configuration
The Configuration Import/Export subsystem provides the ability to import and export managed configurations in a defined JSON document. The exported configuration can then be used to import into another system or back to itself after modifications. What can be imported and exported depends on the configurations being managed.
Be default, all fields are imported unless specified via the 
nonImportableFields
 property. If this property is missing or is empty, all fields will be imported; otherwise, any field names contained in this property are ignored.
The example below shows the payload of the object to be imported, with two items added to the 
nonImportableFields
 list: 
hardwareAddress
 and 
dhcpHostname
.
"com.l7tech.platform.network.dto.NetworkInterfaces" : { "interfaces" : { "eth0" : { "nonImportableFields" : ["hardwareAddress", "dhcpHostname"], "protocol" : "DHCP", "device" : "eth0", "name" : null, "dhcpHostname" : "myapp ", "hardwareAddress" : "00:0C:29:6D:75:56", "onBoot" : true, "ipv4" : null, "ipv6" : null }
Import/Export Configuration commands are accessed from the 
configuration
 sub-shell.
 
Difference Between Restricted Shell vs. Menu Options
When using the restricted shell commands:
  • The "export" command only displays the configurations to export; no exporting is actually performed. Use this to verify your export configuration before actually exporting.
  • The "import" command imports individual bundles of JSON text into the system. 
    Note:
     Using the "Import" command is not recommended, as all special characters require escaping. Use option 
    7
     (Import configuration) instead.
When using the menu options:
  • The "export" option creates a payload file containing the managed configurations.
  • The "import" option imports content from the payload file. No escaping of special characters is required.