swr-application(1)

NAME
swr-application - Cisco IOS Software Router

SYNOPSIS
software_router_image_name [options] instance_number

DESCRIPTION
The Cisco Software Router is a user-space program that provides IP routing services via Cisco`s Internetwork Operating System (IOS). When started as a foreground process, the IOS command line interface (CLI) is presented in the terminal window in which the router is started.

When the Software Router is started it is given an instance number to identify it in communications with other support program, such as swrvcon. The instance_number parameter must be an integer between 0 and 1024. Its default value is 100.

The nvram: file system used by IOS is maintained in a binary file created in the directory from which the Software Router is started. It contains the IOS startup-config file. This file is managed by the Software Router and should not be edited by users. The file name is based on the following naming convention:

    nvram_xxxxx where:

    xxxxx is the five digit instance number (zero filled)

Linux files residing in the directory from which the Software Router is started (and its subdirectories) can be accessed from unix: file system in IOS. Files visible in the unix: file system can be copied to and from other IOS file systems. IOS command output can be directed to files in the unix: file system.

Ethernet intefaces are implemented in the Software Router via emulated four-port Ethernet line cards. The number of emulated line cards is controlled by the -e option (see below). The user may emulate between 1 and 5 line cards. Ethernet interfaces are named using the standard IOS interface naming convention:

    Ethernetx/y where:

    x = slot number (0-4)
    y = port number (0-3)

IOS Ethernet interfaces derive MAC addresses from Linux.

OPTIONS
The following options are specified in the swr-application command line. As an alternative, options can be specified in a SWROPTIONS file described below.

-d  Generate debug information outside of IOS operation. Should only be used under guidance of Cisco support personnel.

-e  Number of four port ethernet line cards to emulate. The default is 2, resulting in eight ethernet interfaces in the Software Router.

-h  Display command help.

-L  Disable the local IOS console. Requires the use of swrvcon to access the IOS console. This mode should be used what starting the Software Router from a Linux initialization script.

-m memory_size
    Software Router memory size in megabytes. The default is 512.

-n machine/storage
    This option specifies the node-lock-type value either machine or storage. If option is specified as "storage" then user can exchange HDD or CF from one machine to another and same license key could be re-used on new machine. Users can not re-use the same license key on different machines when this option is specified as "machine". But can use in differnt filesystems on same machine. The Default is machine.

A sample command line node-lock-type option might be:

 ./c5921i86-universalk9-ms -n storage

-v  This option causes the application to output its current version and then terminate.

-i Interface-mapping
    This option specifies a mapping between a Linux network interface name and a corresponding IOS interface. This option establishes such an association and arranges for internal packet capture from the associated Linux network interface to appear as incoming packets on the associated IOS interface. In addition, it arranges that outgoing packets on the IOS interface to be injected for output on the Linux interface. See "Interface-mapping Command Line Options" below for more information.

-f File-mapping
    This option specifies a mapping of an IOS file system into a corresponding Linux directory. Once this mapping is made, access to the Linux directory can be performed from within IOS. See "File-mapping Command Line Options" below for more information.

-o path
    This option specifies the path in the Linux file system to a SWROPTIONS file. The default for the location of this file is $HOME/SWROPTIONS. This file may or may not exist. If it doesn't exist, then values for options are obtained strictly from the command line. If it does exist, either at the default location or at the location specified using "-o <path>", then options specified in the SWROPTIONS file can be overridden by options specified in the command line. The format of the SWROPTIONS file is explained below.

Interface-mapping Command Line Options
The "-i <interface-mapping> command line option establishes a mapping between a given Linux network interface and a given IOS network interface. The "interface-mapping" consists of a series of sub-options, with each sub-option separated by a colon (':'). Each sub-option consists of a sub-keyword and sub-value, separated by equals ('='). The allowed sub-keywords consist of the following:

type=<raw|tap>
    Two packet capture types are supported: "raw" and "tap". "Raw" interface mapping means that packets are captured and injected directly at the Linux Ethernet driver. This is the preferred mode for general packet capture and injection. "Tap" interface mapping implies the use of a "tap" interface, a kind of virtual network interface that can be attached at one end to various Linux facilities. For example, a "tap" interface can be used as the endpoint for various co-resident applications to communicate with and through the Software Router. It can also be assigned to a bridge group along with a Linux physical network interface to provide packet capture and injection. This sub-option is required.

linux=<linux-network-interface-name>
    The Linux name of the associated interface. For type "raw", this will be the name of an associated physical ethernet interface, such as "eth0", "eth1", etc. For type "tap", this will be the Linux name of the Tap interface, such as "tap0", "tap1", etc. This sub-option is required.

ios=<ios-network-interface-name>
    The IOS name of the associated interface. This will always be of the form "e<n>/<m>", where <n> is a "bay" or "slot" number and <m> is a port number within the bay. There are always 4 ports within each bay or slot. The number of bays/slots is determined by the "-e" command line option. This sub-option is required.

promiscuous(or)prom=<t/f>
    Promiscuous mode. If the sub-value is "t", "T" or "1", then the associated Linux interface will be placed in promiscuous mode. If the sub-value is "f", "F", or "0", then the Linux interface will not be placed in promiscuous mode. The default value for this sub-option is "t", meaning promiscuous mode is enabled. For "raw" interface, if promiscuous mode is TRUE it will process multicast packets, if promiscuous is set to FALSE it will drop multicast packets. For "tap" interfaces, the "promiscuous" mode is ignored.

push-mon-int=<t/f>
    If push-mon-int value is "true", "T", "t" or "1", then speed and duplex cli will be available in IOS side, and if the value is "false", "f" ,"F" or "0" , then speed and duplex cli will not be available in ios side. The default value is false. The speed/duplex cli configured in ios side will get updated to linux side , only when both push-mon-int and monitor-state values are true. If push-mon-int is configured on a "tap" interface, it would be ignored.

A sample command line interface mapping might be:

 -i 'type=raw:linux=eth0:ios=e0/0:prom=false:push-mon-int=true' It is recommended that the entire value portion of the "-i" option be enclosed in single quotes, in order to avoid unanticipated interpretation by the Linux shell. Note that for interface-mappings, the "linux" and "ios" suboptions must specify unique values amongst the set of interface-mappings. Note that it is recommended that you specify interface associations via the SWROPTIONS file rather than in the command line, as described below. It's a lot easier.

File-Mapping Command Line Options
The "-f <file-mapping> command line option establishes a mapping between a given IOS File System name and a given Linux directory. The "file-mapping" consists of a series of sub-options, with each sub-option separated by a colon (':'). Each sub-option consists of a sub-keyword and sub-value, separated by equals ('='). The allowed sub-keywords consist of the following:

ios=<IOS_File_System_Name>
    The "ios" keyword provides the IOS File System name. The value provided to the right of the equals sign must be the IOS File System name. For example, "flash", "flash0", "flash1", "unix", as well as other names, may be used. The IOS File System Name must conform to IOS File System naming conventions. Usually, IOS File System Names end in a colon (":"); however, for this command line option, you omit the colon. This sub-option is required.

linux=<Linux_Directory_Name>
    The sub-value supplied for the "linux" sub-keyword provides a Linux directory to which the IOS file system will be mapped. The directory need not exist at the time the mapping is made; for example, it could name a mountable file system which is not presently mounted. The value supplied must conform to Linux path naming conventions, and it must ultimately name a directory. This sub-option is required.

access=<rw_or_ro>
    This sub-option establishes an access policy for access to the filesystem from IOS. This is in addition to any access policies defined in Linux. The two possible sub-values are "rw", for read and write access; and "ro", for read-only access. This sub-option is optional. The default is "rw".

A sample command line file mapping might be:

-f 'ios=flash0:linux=/tmp:access=rw' Thereafter, any IOS accesses to file system "flash0:" will result in a view into the Linux "/tmp" directory. Any number of mappings may be specified in separate -f options. It is recommended that the entire value portion of the "-f" option be enclosed in single quotes, in order to avoid unanticipated interpretation by the Linux shell. Note that for file-mappings, the "ios" suboption value must be unique amongst the full set of file-mappings. Note that it is recommended that you specify file mappings via the SWROPTIONS file rather than in the command line, as described below. It's a lot easier. Note that by default, the "unix:" IOS file system name is mapped to the current working directory of the process running the application. This can be overridden in a command line file mapping, so that IOS file system "unix:" is mapped to a different Linux directory. However, beware of this, because the application might not run properly because of licensing restrictions. It is recommended that if you are going to re-map the "unix:" IOS file system, you do so before licensing is installed, and that you keep this mapping thereafter.

FILES
SWROPTIONS File The SWROPTIONS File can be used to supply values for options. This provides an ease-of-use feature which makes the command line not quite so complicated. The SWROPTIONS file is optional. The application looks for it by default in $HOME/SWROPTIONS. You can override the default location using the "-o <path>" option as described above. Note again that command line options always override the corresponding values specified in the SWROPTIONS file. The SWROPTIONS file has a simple format consisting of a series of name/value pairs, one per line. Each name/value pair has a colon between the name and the value, with any amount of white space separating the two. The following general options are available:

ethernet-slots
    The value for this option is an integer which specifies the number of Ethernet interface slots. It is overridden by the "-e <n>" command line option. The default value is 2.

debug
    The value for this option is a boolean value. It can be specified as either "true", "t", "1" for TRUE, or "false", "f", or "0" for FALSE. The value is case-insensitive. It governs the output of certain debug information (and is not controlled nor associated with any IOS commands). It is overridden by the "-d" command line option. line option. The default value is FALSE.

ram The value for this option is an integer which specifies how much router memory is in use, in Mbytes. It is overridden by the "-m <n>" command line option. The default value is 512.

local-console-disable
    The value for this option is a boolean value. It can be specified as either "true", "t", "1" for TRUE, or "false", "f", or "0" for FALSE. The value is case-insensitive. It governs whether the router console output is directed to its process standard output (TRUE), or to the virtual console (FALSE). Refer to swrcon(1) for more information on the virtual console. The default value is TRUE. It is overridden by the "-L" command line option.

node-lock-type
    The value for this option is either machine or storage. If node-lock-type is specified as "storage" then user can exchange HDD or CF from one machine to another and same license key could be re-used on new machine. Users can not re-use the same license key on different machines when this option is specified as "machine". But can use in different filesystems on the same machine. The Default is machine.

SWR OPTIONS FILE INTERFACE SECTION
Following the above general options, interface mappings may be specified in the SWR OPTIONS file. Each such interface mapping is in a section of the SWR OPTIONS file delimited by a line containing "[interface]". Once you start an interface section, you may specify a series of keyword=value lines describing a specific interface mapping. Each keyword=value line pertains to a single mapping, up until the next "[interface]" or [filemap] delimiter line, or until the end of the file. Note that all [interface] sections must follow the above general options. The keyword=value lines describing an interface mapping can be any of the following:

type=<raw|tap>
    Two packet capture types are supported: "raw" and "tap". This option is overridden by the "type" sub-option in the -i command line option. This sub-option must be specified.

linux=<linux-network-interface-name>
    The Linux name of the associated interface. For type "raw", this will be the name of an associated physical ethernet interface, such as "eth0", "eth1", etc. For type "tap", this will be the Linux name of the Tap interface, such as "tap0", "tap1", etc. This sub-option must be specified.

ios=<ios-network-interface-name>
    The IOS name of the associated interface. This will always be of the form "e<n>/<m>", where <n> is a "bay" or "slot" number and <m> is a port number within the bay. There are always 4 ports within each bay or slot. The number of bays/slots is determined by the "-e" command line option. This sub-option must be specified. Note that for interface-mappings, the "linux" and "ios" suboptions must specify unique values amongst the set of interface-mappings.

promiscuous(or)prom=<t/f>
    Promiscuous mode. If the sub-value is "t", "T" or "1", then the associated Linux interface will be placed in promiscuous mode. If the sub-value is "f", "F", or "0", then the Linux interface will not be placed in promiscuous mode. The default value for this sub-option is "t", meaning promiscuous mode is enabled. For "tap" interfaces, the "promiscuous" mode is ignored.

push-mon-int=<t/f>
    If push-mon-int value is "true", "T", "t" or "1", then speed and duplex cli will be available in IOS side, and if the value is "false", "f" ,"F" or "0" , then speed and duplex cli will not be available in ios side. The default value is false. The speed/duplex cli configured in ios side will get updated to linux side , only when both push-mon-int and monitor-state values are true. If push-mon-int is configured on a "tap" interface, it would be ignored.

SWR OPTIONS FILEMAP SECTION
Following the above general options, file mappings may be specified in the SWR OPTIONS file. Each file mapping establishes a mapping between a given IOS File System name and a given Linux directory. Each such file mapping is in a section of the SWR OPTIONS file delimited by a line containing "[filemap]". Once you start a Filemap section, you may specify a series of keyword=value lines describing a specific file mapping. Each keyword=value line pertains to a single mapping, up until the next [filemap] or [interface] delimiter line, or until the end of the file. Note that all [filemap] sections must follow the above general options. The keyword=value lines describing a file mapping can be any of the following:

ios=<IOS_File_System_Name>
    The "ios" keyword provides the IOS File System name. The value provided to the right of the equals sign must be the IOS File System name. For example, "flash", "flash0", "flash1", "unix", as well as other names, may be used. The IOS File System Name must conform to IOS File System naming conventions. Usually, IOS File System Names end in a colon (":"); however, for this command line option, you omit the colon. This sub-option is required.

linux=<Linux_Directory_Name>
    The sub-value supplied for the "linux" sub-keyword provides a Linux directory to which the IOS file system will be mapped. The directory need not exist at the time the mapping is made; for example, it could name a mountable file system which is not presently mounted. The value supplied must conform to Linux path naming conventions, and it must ultimately name a directory. This sub-option is required.

access=<rw_or_ro>
    This sub-option establishes an access policy for access to the filesystem from IOS. This is in addition to any access policies defined in Linux. The two possible sub-values are "rw", for read and write access; and "ro", for read-only access. This sub-option is optional. The default is "rw".

SAMPLE SWR OPTIONS FILE
 # Comment
 ethernet-slots=2
 debug=f
 node-lock-type=machine

 [interface]
 linux=eth0
 ios=e0/0
 type=raw

 [interface]
 linux=eth1
 ios=e0/1
 type=raw

 [filemap]
 ios=flash0
 linux=/tmp
 access=rw

SEE ALSO
swrvcon(1) swroptions(1)

COPYRIGHT
Copyright (c) 2013 by Cisco systems, Inc.