1. Manuals
  2. Tumbleweed
  3. vpcs
  4. vpcs(1)

Scroll to navigation

VPCS(1) Virtual PC Simulator VPCS(1)

NAME

vpcs - Virtual PC Simulator

SYNOPSIS

vpcs [OPTIONS] [FILENAME]

DESCRIPTION

VPCS provides a command line interface to nine simulated virtual PCs. You can ping/trace route from/to them, or ping/trace route other hosts/routers from the virtual PCs, making it an ideal study tool when you simulate Cisco or Juniper routers in a Dynamips or GNS3 environment.

Virtual PCs are able to generate and respond to ICMP (ping), TCP and UDP packets delivered to the application via a UDP pipe or Unix tap interface. If scriptfile is specified, then vpcs reads the file on start-up and executes the commands in the scriptfile. scriptfile must be in vpcs script file format.

vpcs listens for messages on nine consecutive UDP ports and sends messages on nine consecutive UDP ports. By the default, vpcs listens on UDP ports 20000 to 20008 and sends messages on UDP ports 30000 to 30008. Each UDP port pair (20000/30000, 20001/30001...20008/30008) represents a virtual PC. Virtual PCs are numbered 1 to 9.

OPTIONS

Print the command line options and exit
Print the version information and exit
Disable the relay function
[-i] num
Start vpcs with num vitrual PCs, maximum 9. If omitted vpcs will start with 9 virtual PCs. If num is 1, such as when GNS3 v1.x spawns PCs, commands that reference other PCs will have restricted options and the prompt will not display the PC number.
Run vpcs as a daemon process listening on TCP port specified by port. As a daemon process, vpcs does not present a command line interface to the user, but the command line interface can be accessed remotely using a TCP stream application such as telnet or netcat (nc). Once the daemon has been started, there is no internal mechanism for terminating the program, and the program must be terminated by sending a system signal 9, typically by using the command kill -9 PID (where PID is the process id of the vpcs instance)
vpcs uses 9 consecutive MAC addresses for the 9 vpcs stating at 00:50:79:66:68:00 by default. The -m option adds num to the last byte of the base MAC address. Should any increment cause the last byte exceed 0xFF during this process, it will increment to 0x00.
[-r] FILENAME
If FILENAME is specified, then vpcs reads the file on start-up and executes the commands in the FILENAME. FILENAME must be in vpcs script file format. By default, if a file named startup.vpc exists in the directory where the vpcs program was started, it will be read and executed when vpcs starts. The -r option is optional if FILENAME is the last parameter.
On systems that support the /dev/tapx interface (Unix/Linux), run vpcs in tap mode rather than UDP mode. In tap mode, IP packets are sent and received via /dev/tapx interfaces rather than via UDP streams. Typically /dev/tapx interfaces are only available to the root user, meaning vpcs would also be required to be run by the root user (sudo vpcs -e) to use tap mode.
[-u]
This option is the default and not necessary, but included to contrast with the -e option. By default, vpcs sends and receives IP packets to and from specified UDP ports. vpcs listens on UDP port 20000 and sends to port 127.0.0.1:30000 by default. The listening and sending ports can be manipulated using the -s, -c and -t options.

UDP Mode Options

port specifies the base port number that vpcs uses to listen for messages. By default vpcs listens for messages on UDP ports 20000 to 20008. By changing the base port that vpcs listens to using the -s option causes nine consecutive UDP ports to be used starting at the port specified by port.
vpcs streams packets to nine UDP ports commencing at 127.0.0.1:30000 by default. The -t option allows you to stream packets to a remote host as specified by IPv4 address ip. Typically the remote host will be running dynamips with a cloud connection configured to link to this host’s IP address.
vpcs streams packets to nine UDP ports commencing at 127.0.0.1:30000. The -c option allows you to stream packets to a different set of nine ports commencing at the base port number specified by port.

TAP Mode Options

Device name, works only when -i is set to 1

Hypervisor Mode Option

Run as a hypervisor, listening on TCP port specified by port. In the hypervisor mode, you can connect this control port with telnet, start or stop an instance of vpcs.

EXAMPLES

No command line options

If you start the vpcs with no arguments, vpcs will start and look for the script startup.vpc in the current directory. If it exists, it will run the script. This is the normal way of running the vpcs. It is simply evoked from the command line like this:

vpcs

Starting vpcs with an alternative startup file

To start vpcs with a startup script file called say alternate.vpc, use the file name as an argument to the vpcs command:

vpcs alternate.vpc

Running more than nine Virtual PCs

Suppose you needed more than nine Virtual PCs, so you want to run a second instance of vpcs on your local host. You would have to consider:

1. The VPCs MAC addresses for the second instance would need to be different,

2. The "local" or listening UDP port numbers for the second instance would have to differ from the first instance.

3. The remote UDP port numbers for the second instance would have to differ from the first instance.

Since the default local listening port is 20000, and the default remote port is 30000, you would want to start vpcs with a local listening port of 20009 (or greater) and remote port of 30009 (or greater) . You would also want the base MAC address to be offset by at least nine to avoid any clashes. In this case you would use the command:

vpcs -s 20009 -c 30009 -m 9

A far better way to run more than nine Virtual PCs is to use the Hypervisor mode. In Hypervisor mode, vpcs will automatically take care of incrementing MAC addresses and UDP port numbers so here is no clash.

BASE INTERFACE

vpcs presents the user with a command line interface (unless daemon mode has been invoked by the -p option). The interface prompt indicates which of the 9 virtual PCs currently has focus by indicating the VPC number in brackets. Eg.:
VPCS[1]>
Here the digit 1 inside the brackets indicates that VPC 1 has focus, and any traffic generated will be sent from VPC 1, and basic show commands will relate to VPC 1.

Note: When started with the -i 1 option, VPC 1 always has focus, and the prompt does NOT display the VPC number in brackets. Eg.:
VPCS>

Basic commands supported are:

?
Print help
Switch to the VPCdigit. digit range 1 to 9
Shortcut for: show arp. Show arp table for VPC digit (default this VPC) or all VPCs
Clear IPv4/IPv6, arp/neighbor cache, command history
Shortcut for: ip dhcp. Attempt to obtain IPv4 address, mask, gateway and DNS via DHCP
Exit the telnet session (daemon mode)
Display TEXT in output
Print help
Shortcut for: show history. List the command history
Configure the current VPC's IP settings
address [mask] [gateway]
address [gateway] [mask]

Set the VPC's ip, default gateway ip and network mask. Default IPv4 mask is /24, IPv6 is /64. Example:
ip 10.1.1.70/26 10.1.1.65 sets the VPC's ip to 10.1.1.70, the gateway to 10.1.1.65, the netmask to 255.255.255.192.
In tap mode, the ip of the tapx is the maximum host ID of the subnet. In the example above the tapx ip would be 10.1.1.126
mask may be written as /26, 26 or 255.255.255.192

Attempt to obtain IPv6 address, mask and gateway using SLAAC
Attempt to obtain IPv4 address, mask, gateway, DNS via DHCP
OPTION:
-d Show DHCP packet decode
-r Renew DHCP lease
-x Release DHCP lease
Set DNS server ip, delete if ip is '0'
Set local domain name to NAME. The domain name will be added to host names when using commands that support names. Example: If the domain name was set to example.com, then a command of ping abcd would cause the VPCS to attempt to resolve the name abcd.example.com.
Load the configuration/scriptfile from the file FILENAME. If FILENAME ends with '.vpc', then the '.vpc' can be omitted. If FILENAME is omitted then startup.vpc will be loaded if it exists. When the file is loaded, each line of the file is executed as a VPCS command. If the state of the echo flag is on, the command will be echoed to the console before execution, except:

*
If the command is prefixed with a '@' symbol (eg @set echo color red);

*
If the command is an echo command;

*
If the command is a sleep command
Note: The command sleep 0 will be echoed if the echo flag is on
See set echo and show echo

Note: Press Ctrl+C to interrupt the running script.

Ping the network HOST with ICMP (default) or TCP/UDP. HOST can be an ip address or name
OPTIONS:
-1 ICMP mode, default
-2 UDP mode
-3 TCP mode
-c count Packet count, default 5
-D Set the Don't Fragment bit
-f FLAG Tcp header FLAG |C|E|U|A|P|R|S|F|
bits |7 6 5 4 3 2 1 0|
-i ms Wait ms milliseconds between sending each packet
-l size Data size
-P protocol Use IP protocol in ping packets
1 - ICMP (default), 17 - UDP, 6 - TCP
-p port Destination port
-s port Source port
-T ttl Set ttl, default 64
-t Send packets until interrupted by Ctrl+C
-w ms Wait ms milliseconds to receive the response
Notes: 1. Using names requires DNS to be set.
2. Use Ctrl+C to stop the command.
Quit program
Configure packet relay between UDP ports.

The relay command allows the VPCS to become a virtual patch panel where connections can be dynamically changed using the relay command. There are three steps required to use VPCS as a virtual patch panel.


1.
A relay hub port must be defined using the relay port port command.

2.
Remote NIO_UDP connections (cloud connections in GNS3) use this hub port as the remote port, ensuring each NIO_UDP connection has a unique local port. (The local port numbers will be used to 'patch' the connection). VPC instances can be directed to use this hub port as their remote port using the command set rport port.

3. The 'patching' is completed using the command:

relay add [ip1:]port1 [ip2:]port2, where port1 and port2 are the local port numbers used in step 2.
Relay the packets between ip1 and ip2
Delete the relay rule
Delete the relay rule
Dump relay packets to file
Set relay hub port
Show the relay rules

Note: ip1 and ip2 are 127.0.0.1 by default

Telnet to port on host at ip (relative to host PC). To attach to the console of a virtual router running on port 2000 of this host PC, use rlogin 2000
To telnet to the port 2004 of a remote host 10.1.1.1, use rlogin 10.1.1.1 2004
Save the configuration to the scriptfile FILENAME.vpc. If there is no '.' in FILENAME then a '.vpc' extension is added. If FILENAME is omitted then the configuration will be saved to startup.vpc
Set hostname, connection port, ipfrag state, dump options and echo options
Set the packet dump flags for this VPC.


FLAG:

All the packets including incoming.
must use [detail|mac|raw] as well as 'all'
Print protocol
Dump packets to file vpcs[id]_yyyymmddHHMMSS.pcap'
Clear all the flags
Print hardware MAC address
Print the first 40 bytes
Sets the state of the echo flag used when executing script files, or sets the color of text to FGCOLOR with optional BGCOLOR. set echo color clear resets colors to their defaults.
Color list: black, red, green, yellow, blue, magenta, cyan, white
Local port
Set the size of the maximum transmission unit of the interface
Set the hostname of the current VPC to NAME
Remote peer port
Remote peer host IPv4 address
Show information for ARG
Show arp table for VPC digit or all VPCs
Show dump flags for VPC digit or all VPCs
Show the status of the echo flag. See set echo ?
List the command history
Show IPv4 details for VPC digit or all VPCs. Shows VPC Name, IP address, mask, gateway, DNS, MAC, lport, rhost:rport and MTU
Show IPv6 details for VPC digit or all VPCs. Shows VPC Name, IPv6 addresses/mask, gateway, MAC, lport, rhost:rport and MTU
Show the version information

Notes:
1. If no parameter is given, the key information of all VPCs will be displayed
2. If no parameter is given for arp/dump/ip/ipv6 information for the current VPC will be displayed.

Print text and pause execution of script for time seconds. If seconds is zero or missing, pause until a key is pressed. Default text when no parameters given: 'Press any key to continue'
Print the path packets take to the network HOST. HOST can be an ip address or name.
Use IP protocol in trace packets
1 - icmp, 17 - udp (default), 6 - tcp
Maximum ttl, default 8


Notes: 1. Using names requires DNS to be set.
2. Use Ctrl+C to stop the command.

Shortcut for: show version
Do the same as save

VPCS script file format

Any text file consisting of valid vpcs commands can be used as a vpcs script file. Lines in the file beginning with the # character will be treated as comments and ignored. As the script is being executed, the VPCS will either display each command immediately before it is executed or not depending on the state of the echo flag. The @ character can also be used to supress command echoing. Commands pre-pended by the @ character are not echoed. The echo and sleep commands are never echoed except the sleep 0 command which is always echoed.

Command files can make use of the echo and sleep commands to create some form of interactive script.

Script file exececution can be aborted at any time by pressing Ctrl+c. This means that the ping HOST -t command (which must be terimated by Ctrl+c) is not useful in vpcs script files.

HYPERVISOR INTERFACE

When vpcs is started with the -H port option, vpcs starts in hypervisor mode as a daemon process.

To access the vpcs hypervisor interface, you need to start a telnet session to the port number you specified with the -H option. If for example you started vpcs with a command of vpcs -H 20000, then you would typically open a telnet session to port 20000 on your localhost IP address (127.0.0.1).

In this mode, an alternative interface is presented to allow the user to create and kill multiple vpcs sessions. These sessions are always run as a daemon process and must be accessed via either an external telnet application, or by using the telnet or rlogin command within the vpcs hypervisor session.

Print help
Exit the telnet session
List vpcs process and ids
Stop all vpcs processes and hypervisor, -f force quit without prompting
Stop vpcs process number id
Same as telnet
Telnet to port at ip (default 127.0.0.1)
Start vpcs daemon with parameters.

A typical hypervisor session might run something like this:

-------------------------------------------------------
~$ vpcs -H 20000
~$ telnet 127.0.0.1 20000
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
HV > vpcs
100-VPCS started with -p 20001 -s 20000 -c 30000
HV > rlogin 20001
Connect 127.0.0.1:20001, press Ctrl+X to quit
NOTES: you will be back to the starting point, NOT THE LAST,
if using Ctrl+X to quit.

Welcome to Virtual PC Simulator, ... <output omitted> ...
VPCS[1] disconnect
Good-bye
Disconnected from 127.0.0.1:20001
HV >
-------------------------------------------------------

Note that when the vpcs instance was initiated from within the hypervisor interface, it spawned a vpcs daemon process listening on TCP port 20001. To access that process, the rlogin command was used to port 20001 initiating a session with that instance. However, you could have just as easily started another independent telnet session in another shell instance to 127.0.0.1 20001.

Also note that once you have finished with the vpcs session, you can exit either using the disconnect command, or use the key combination of Ctrl+X. If you have nested rlogin sessions, Ctrl+X will return you to the hypervisor, disconnect will take you back one level in the nesting.

BUGS

IPv6 implementation is a basic implementation that is not fully implemented.

The ping HOST -t command (which must be terminated by Ctrl+c) can not be used in vpcs script files because when Ctrl+c is pressed to stop the ping, it also aborts the script file execution.

Please send problems, bugs, questions, desirable enhancements, patches etc to the author.

AUTHOR

Paul Meng <mirnshi[AT]gmail.com>
Documentation by Chris Welsh <rednectar.chris[AT]gmail.com>

COPYRIGHT

VPCS is free software, distributed under the terms of the "BSD" licence.
Source code and license can be found at vpcs.sf.net.
For more information, please visit wiki.freecode.com.cn.

2013-12-16 0.8