.TH VPCS "1" "2014-06-28" "0.5" "Virtual PC Simulator" .\" Last revision: 2014-06-28 16:25:50 .hy 0 .if n .ad l .SH NAME vpcs \- Virtual PC Simulator .SH SYNOPSIS .B vpcs [\fIoptions\fR] [\fIscriptfile\fR] .SH DESCRIPTION .PP 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. .PP 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 \fIscriptfile\fR is specified, then vpcs reads the file on start-up and executes the commands in the scriptfile. \fIscriptfile\fR must be in \fBvpcs script file format\fR. .PP \fBvpcs\fR listens for messages on nine consecutive UDP ports and sends messages on nine consecutive UDP ports. By the default, \fBvpcs\fR 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. .SH OPTIONS .TP \fB-h\fR, \fB--help\fR Print the command line options and exit .TP \fB-v\fR Print the version information and exit .TP \fB-i\fR \fInum\fR number of vpc instances to start (default is 9) .TP [\fB-r\fR] \fIscriptfile\fR If \fIscriptfile\fR is specified, then \fBvpcs\fR reads the file on start-up and executes the commands in the \fIscriptfile\fR. \fIscriptfile \fR must be in \fBvpcs\fR script file format. By default, if a file named \fBstartup.vpc\fR exists in the directory where the \fBvpcs\fR program was started, it will be read and executed when \fBvpcs\fR starts. The \fB-r\fR option is optional if \fIscriptfile\fR is the last parameter. .TP \fB-p\fR \fIport\fR Run \fBvpcs\fR as a daemon process listening on TCP port specified by \fIport\fR. As a daemon process, \fBvpcs\fR 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 \fItelnet\fR or netcat (\fInc\fR). 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 \fBkill \-9 PID\fR (where PID is the process id of the vpcs instance) .TP \fB-m\fR \fInum\fR \fBvpcs\fR uses 9 consecutive MAC addresses for the 9 \fIvpcs\fR stating at 00:50:79:66:68:00 by default. The \fB-m\fR option adds \fInum\fR 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. .TP \fB-e\fR On systems that support the \fB/dev/tapx\fR interface (Unix/Linux), run \fBvpcs\fR 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 \fBvpcs\fR would also be required to be run by the root user (\fBsudo vpcs \-e\fR) to use tap mode. .TP [\fB-u\fR] This option is the default and not necessary, but included to contrast with the \fB-e\fR option. By default, \fBvpcs\fR sends and receives IP packets to and from specified UDP ports. \fBvpcs\fR 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 \fB-s\fR, \fB-c\fR and \fB-t\fR options. .SS "UDP Mode Options" .TP \fB-s\fR \fIport\fR \fIport\fR specifies the base port number that \fBvpcs\fR uses to listen for messages. By default \fBvpcs\fR listens for messages on UDP ports \fI20000\fR to \fI20008\fR. By changing the base port that \fBvpcs\fR listens to using the \fB-s\fR option causes nine consecutive UDP ports to be used starting at the port specified by \fIport\fR. .TP \fB-t\fR \fIip\fR \fBvpcs\fR streams packets to nine UDP ports commencing at \fI127.0.0.1:30000\fR by default. The \fB-t\fR option allows you to stream packets to a remote host as specified by IPv4 address \fIip\fR. Typically the remote host will be running dynamips with a cloud connection configured to link to this host’s IP address. .TP \fB-c\fR \fIport\fR \fBvpcs\fR streams packets to nine UDP ports commencing at \fI127.0.0.1:30000\fR. The \fB-c\fR option allows you to stream packets to a different set of nine ports commencing at the base port number specified by \fIport\fR. .SS "TAP Mode Options" .TP \fB-d\fR \fIdevice\fR Device name, works only when \fB-i\fR is set to 1 .SS "Hypervisor Mode Option" .TP \fB-H\fR \fIport\fR Run as a hypervisor, listening on TCP port specified by \fIport\fR. In the hypervisor mode, you can connect this control \fIport\fR with \fItelnet\fR, start or stop an instance of \fBvpcs\fR. .SH EXAMPLES .SS "No command line options" If you start the \fBvpcs\fR with no arguments, \fIvpcs\fR will start and look for the script \fBstartup.vpc\fR in the current directory. If it exists, it will run the script. This is the normal way of running the \fIvpcs\fR. It is simply envoked from the command line like this: .PP \fBvpcs\fR .PP .SS "Starting vpcs with an alternative startup file" To start \fBvpcs\fR with a startup script file called say \fBalternate.vpc\fR, use the file name as an argument to the \fBvpcs\fR command: .PP \fBvpcs alternate.vpc\fR .SS "Running more than nine Virtual PCs" Suppose you needed more than nine Virtual PCs, so you want to run a second instance of \fBvpcs\fR on your local host. You would have to consider: .PP 1. The VPCs MAC addresses for the second instance would need to be different, .PP 2. The "local" or listening UDP port numbers for the second instance would have to differ from the first instance. .PP 3. The remote UDP port numbers for the second instance would have to differ from the first instance. .PP Since the default local listening port is 20000, and the default remote port is 30000, you would want to start \fBvpcs\fR 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: .PP \fBvpcs \-s 20009 \-c 30009 \-m 9\fR .SS "Running two instances of vpcs that can communicate with each other on the one host" Suppose you wanted to run a second instance of \fBvpcs\fR on your local host that can communicate with the instance already running with a default configuration. You would have to consider: .PP 1. The VPCs MAC addresses for the second instance would need to be different, .PP 2. The "local" or listening UDP port numbers for the second instance would have to match the "remote" port numbers of the first instance .PP 3. The remote UDP port numbers would have to match the "local" or listening UDP port numbers of the first instance .PP Since the default local listening port is 20000, and the default remote port is 30000, you would want to start \fBvpcs\fR with a local listening port of 30000 and remote port of 20000. 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: .PP \fBvpcs \-s 30000 \-c 20000 \-m 9\fR .SH BASE INTERFACE \fBvpcs\fR presents the user with a command line interface (unless daemon mode has been invoked by the \fB-p\fR option). The interface prompt indicates which of the 9 virtual PCs currently has focus by indicating the VPC number in brackets. Eg.: .br VPCS[1] .br Here the digit 1 inside the brackets indcates that VPC 1 has focus, and any traffic generated will be sent from VPC 1, and basic \fBshow\fR commands will relate to VPC 1. .br .TP 25 Basic commands supported are: .TP \fB?\fR Print help .TP \fB\fR Switch to the VPC. range 1 to 9 .TP \fBarp\fR Shortcut for: \fBshow arp\fR. Show arp table .TP \fBclear\fR [arguments] Clear IPv4/IPv6, arp/neighbor cache, command history .TP \fBdhcp\fR [\-options] Shortcut for: \fBip dhcp\fR. Get IPv4 address via DHCP .TP \fBecho\fR Display in output .TP \fBhelp\fR Print help .TP \fBhistory\fR Shortcut for: \fBshow history\fR. List the command history .TP \fBip\fR [arguments] Configure VPC's IP settings .TP \fBload\fR Load the configuration/script from the file .TP \fBping\fR [\-options] Ping the network with ICMP (default) or TCP/UDP .TP \fBquit\fR Quit program .TP \fBrelay\fR [arguments] Relay packets between two UDP port .TP \fBrlogin\fR [] Telnet to host relative to HOST PC .TP \fBsave\fR Save the configuration to the file .TP \fBset\fR [arguments] Set VPC name, peer ports, dump options, echo on or off .TP \fBshow\fR [arguments] Print the information of VPCs (default). Try \fBshow ?\fR .TP \fBsleep\fR [text] Print and pause the running script for .TP \fBtrace\fR [\-options] Print the path packets take to network .TP \fBversion\fR Shortcut for: \fBshow version\fR .SS "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 \fB#\fR character will be treated as comments and ignored. Command files can make use of the \fBecho\fR and \fBsleep\fR commands to create some form of interactive script. .br Script file exececution can be aborted at any time by pressing Ctrl+c. This means that the \fBping \-t\fR command (which must be terimated by Ctrl+c) is not useful in vpcs script files. .SH HYPERVISOR INTERFACE .TP 25 commands supported are: .TP \fBhelp | ?\fR Print help .TP \fBvpcs\fR [parameters] Start \fBvpcs\fR daemon with parameters. .TP \fBstop id\fR Stop \fBvpcs\fR process .TP \fBlist\fR List \fBvpcs\fR process .TP \fBdisconnect\fR Exit the telnet session .TP \fBquit\fR [\-f] Stop \fBvpcs\fR processes and hypervisor, \fI-f\fR force quit without prompting .TP \fBtelnet [] \fR Telnet to at (default 127.0.0.1) .TP \fBrlogin [] \fR Same as telnet .SH BUGS IPv6 implementation is a basic implementation that is not fully implemented. .PP The \fBping \-t\fR command (which must be terimated 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. .PP Please send problems, bugs, questions, desirable enhancements, patches etc to the author. .SH AUTHOR Paul Meng .br Documentation by Chris Welsh .SH COPYRIGHT VPCS is free software, distributed under the terms of the "BSD" licence. .br Source code and license can be found at vpcs.sf.net. .br For more information, please visit wiki.freecode.com.cn.