VPCS(1)

📦
version 0.8.3 · 3 versions
, in nixos 26.05, opensuse-leap 16.0, ubuntu resolute, ubuntu stonking

💖 VPCS — Virtual PC Simulator 💖

okay bestie, welcome to vpcs(1) — that's the manual page for VPCS, the Virtual PC Simulator. it's giving "study buddy for your network labs" and honestly? iconic. let's get into it 🫶

✨ SYNOPSIS ✨

vpcs [OPTIONS] [FILENAME]

🌸 DESCRIPTION 🌸

so basically, VPCS hands you a command line interface to nine simulated virtual PCs. you can ping and traceroute from them, to them, and out to other hosts and routers — which makes it the study tool when you're simulating Cisco or Juniper routers in a Dynamips or GNS3 environment. periodt. 👑

these virtual PCs can generate and respond to ICMP (ping), TCP and UDP packets, and those packets get delivered to the application through either a UDP pipe or a Unix tap interface. your choice, your vibe.

if scriptfile is specified, then vpcs reads that file on start-up and runs the commands inside it. heads up though — scriptfile must be in vpcs script file format. no random files, bestie, it will not read your grocery list.

here's the networking tea ☕: vpcs listens for messages on nine consecutive UDP ports and sends messages on nine consecutive UDP ports. by default, it listens on UDP ports 20000 to 20008 and sends on UDP ports 30000 to 30008. each UDP port pair is one virtual PC — 20000/30000, 20001/30001 … all the way to 20008/30008. and the virtual PCs are numbered 1 to 9. cute, right? ✨

💅 OPTIONS 💅

  • -h, --help — prints the command line options and then exits. the "wait what were the flags again" button, we love her.
  • -v — prints the version information and exits.
  • -R — disables the relay function.
  • [-i] num — start vpcs with num virtual PCs, maximum 9. if you omit it, vpcs starts with 9 virtual PCs. and if num is 1 — like when GNS3 v1.x spawns PCs — then commands that reference other PCs get restricted options, and the prompt won't display the PC number.
  • -p port — run vpcs as a daemon process listening on the TCP port specified by port. as a daemon it gives you no command line interface at all, but you can still reach that CLI remotely with a TCP stream application like telnet or netcat (nc). > ⚠️ real talk: once the daemon has started, there is no internal mechanism for terminating the program. you have to kill it with a system signal 9, usually via kill -9 PID (where PID is the process id of the vpcs instance). so like, remember the PID, bestie 😭
  • -m num — vpcs uses 9 consecutive MAC addresses for the 9 vpcs, starting at 00:50:79:66:68:00 by default. the -m option adds num to the last byte of the base MAC address. and if any increment makes that last byte exceed 0xFF during this process, it wraps around to 0x00. she's modular, she's efficient 💫
  • [-r] FILENAME — if FILENAME is specified, vpcs reads the file on start-up and executes the commands in it. 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'll be read and executed when vpcs starts. and fun fact: the -r option is optional if FILENAME is the last parameter. lowkey generous of her.
  • -e — on systems that support the /dev/tapx interface (Unix/Linux), run vpcs in tap mode instead of UDP mode. in tap mode, IP packets are sent and received via /dev/tapx interfaces rather than UDP streams. > ⚠️ typically /dev/tapx interfaces are only available to the root user, which means vpcs would also need to be run by root (sudo vpcs -e) to use tap mode. sudo era 💀
  • [-u] — this option is the default and not necessary at all, but it's here to contrast with the -e option. by default, vpcs sends and receives IP packets to and from specified UDP ports: it listens on UDP port 20000 and sends to 127.0.0.1:30000 by default. and you can manipulate those listening and sending ports using the -s, -c and -t options. she's the baseline, the blueprint, the default queen 🌈

🦋 UDP Mode Options 🦋

  • -s port — port specifies the base port number that vpcs uses to listen for messages. by default vpcs listens on UDP ports 20000 to 20008. changing the base port with -s makes it use nine consecutive UDP ports starting at the port you specify.
  • -t ip — vpcs streams packets to nine UDP ports, starting at 127.0.0.1:30000 by default. the -t option lets you stream those packets to a remote host specified by IPv4 address ip. typically that remote host is running dynamips with a cloud connection configured to link to this host's IP address. long-distance relationship, but make it packets 📡
  • -c port — vpcs streams packets to nine UDP ports commencing at 127.0.0.1:30000. the -c option lets you stream those packets to a different set of nine ports, starting at the base port number specified by port.

🧚 TAP Mode Options 🧚

  • -d device — device name. works only when -i is set to 1. that's the whole rule, don't fight it 💅

👑 Hypervisor Mode Option 👑

  • -H port — run as a hypervisor, listening on the TCP port specified by port. in hypervisor mode you can connect this control port with telnet and start or stop an instance of vpcs. main character energy fr fr.

🌟 EXAMPLES 🌟

🍓 No command line options

if you start vpcs with no arguments, it starts up and looks for the script startup.vpc in the current directory. if that file exists, it runs the script. this is the normal way of running vpcs — just evoke it 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, just use the file name as an argument to the vpcs command:

vpcs alternate.vpc

🍓 Running more than nine Virtual PCs

so suppose you need more than nine Virtual PCs — you'd want to run a second instance of vpcs on your local host. before you do, 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'd want to start vpcs with a local listening port of 20009 (or greater) and a remote port of 30009 (or greater). you'd also want the base MAC address offset by at least nine to avoid any clashes. in that case you'd use the command:

vpcs -s 20009 -c 30009 -m 9

but honestly? a far better way to run more than nine Virtual PCs is to use Hypervisor mode. in Hypervisor mode, vpcs automatically takes care of incrementing MAC addresses and UDP port numbers, so there's no clash. she handles the admin for you, bestie 🫶

✨ BASE INTERFACE ✨

okay bestie, so vpcs serves up a command line interface (unless you started it in daemon mode with the -p option). The prompt tells you which of the 9 virtual PCs is currently the main character by showing the VPC number in brackets. Like:

VPCS[1]>

That 1 in the brackets means VPC 1 has focus. Any traffic you make comes from VPC 1, and basic show commands are all about VPC 1. 💅

Note: If you started with -i 1, then VPC 1 always has focus, and the prompt does not show the VPC number in brackets. Like:
VPCS>

🎀 Basic commands supported are: 🎀

  • ? — Print help 💁‍♀️
  • digit — Switch to the VPCdigit. digit range 1 to 9 🔢
  • arp [digit|all] — Shortcut for: show arp. Show arp table for VPC digit (default this VPC) or all VPCs 🕵️‍♀️
  • clear ip|ipv6|arp|neighbor|hist — Clear IPv4/IPv6, arp/neighbor cache, command history 🧹
  • dhcp [OPTION] — Shortcut for: ip dhcp. Attempt to obtain IPv4 address, mask, gateway and DNS via DHCP 📡
  • disconnect — Exit the telnet session (daemon mode) 👋
  • echo TEXT — Display TEXT in output 🗣️
  • help — Print help 🆘
  • history — Shortcut for: show history. List the command history 📜
  • ip ARG ... [OPTION] — Configure the current VPC's IP settings
    • ARG ...:
      • 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.
      • auto
        • Attempt to obtain IPv6 address, mask and gateway using SLAAC.
      • dhcp [OPTION]
        • Attempt to obtain IPv4 address, mask, gateway, DNS via DHCP
        • OPTION:
          • -d — Show DHCP packet decode
          • -r — Renew DHCP lease
          • -x — Release DHCP lease
      • dns ip
        • Set DNS server ip, delete if ip is '0'
      • domain NAME
        • 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 [FILENAME[.vpc]] — 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 HOST [OPTION ...] — 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 — Quit program 🚪
  • relay ARG ... — 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.
    • ARG:
      • add [ip1:]port1 [ip2:]port2 — Relay the packets between ip1 and ip2
      • del [ip1:]port1 [ip2:]port2 — Delete the relay rule
      • del id — Delete the relay rule
      • dump [on|off] — Dump relay packets to file
      • port port — Set relay hub port
      • show — Show the relay rules
Note: ip1 and ip2 are 127.0.0.1 by default
  • rlogin [ip] port — 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 [FILENAME[.vpc]] — 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 ARG ... — Set hostname, connection port, ipfrag state, dump options and echo options
    • ARG:
      • dump FLAG [[FLAG]...] — Set the packet dump flags for this VPC.
        • FLAG:
          • all — All the packets including incoming. must use [detail|mac|raw] as well as 'all'
          • detail — Print protocol
          • file — Dump packets to file vpcs[id]_yyyymmddHHMMSS.pcap'
          • off — Clear all the flags
          • mac — Print hardware MAC address
          • raw — Print the first 40 bytes
      • echo on|off|[color clear|FGCOLOR [BGCOLOR]] — 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
      • lport port — Local port
      • mtu value — Set the size of the maximum transmission unit of the interface
      • pcname NAME — Set the hostname of the current VPC to NAME
      • rport port — Remote peer port
      • rhost ip — Remote peer host IPv4 address
  • show [ARG ...] — Show information for ARG
    • ARG:
      • arp [digit|all] — Show arp table for VPC digit or all VPCs
      • dump [digit|all] — Show dump flags for VPC digit or all VPCs
      • echo — Show the status of the echo flag. See set echo ?
      • history — List the command history
      • ip [digit|all] — Show IPv4 details for VPC digit or all VPCs. Shows VPC Name, IP address, mask, gateway, DNS, MAC, lport, rhost:rport and MTU
      • ipv6 [digit|all] — Show IPv6 details for VPC digit or all VPCs. Shows VPC Name, IPv6 addresses/mask, gateway, MAC, lport, rhost:rport and MTU
      • version — 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.
  • sleep [seconds] [text] — 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'.
  • trace HOST [OPTION ...] — Print the path packets take to the network HOST. HOST can be an ip address or name.
    • OPTIONS:
      • -P protocol — Use IP protocol in trace packets
        • 1 - icmp, 17 - udp (default), 6 - tcp
      • -m ttl — Maximum ttl, default 8
Notes: 1. Using names requires DNS to be set. 2. Use Ctrl+C to stop the command.
  • version — Shortcut for: show version
  • write [FILENAME[.vpc]] — 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 execution can be aborted at any time by pressing Ctrl+c. This means that the ping HOST -t command (which must be terminated by Ctrl+c) is not useful in vpcs script files.

🦋 HYPERVISOR INTERFACE 🦋

Okay so this is the main character mode, bestie. When you start vpcs with the -H port option, it goes full hypervisor mode and runs as a daemon process. It's giving manager energy.

To get into the vpcs hypervisor interface, you open a telnet session to whatever port number you gave the -H option. Like, say you ran vpcs -H 20000 — then you'd normally telnet to port 20000 on your localhost IP address (127.0.0.1). Iconic, right?

In this mode you get a whole different interface so you can create and kill multiple vpcs sessions. Heads up: those sessions are always run as a daemon process, and you have to reach them either through an external telnet app, or by using the telnet or rlogin command from inside the vpcs hypervisor session itself. 🫶

So in hypervisor mode, here's the command menu, and it's short and sweet:

  • help | ? — Print help
  • disconnect — Exit the telnet session
  • list — List vpcs process and ids
  • quit [-f] — Stop all vpcs processes and hypervisor. -f = force quit without prompting
  • stop id — Stop vpcs process number id
  • rlogin [ip] port — Same as telnet
  • telnet [ip] port — Telnet to port at ip (default 127.0.0.1)
  • vpcs [parameters] — 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 >
-------------------------------------------------------

Okay so notice — when the vpcs instance was started from inside the hypervisor interface, it spawned a vpcs daemon process listening on TCP port 20001. To get at that process, the rlogin command was used to port 20001, which kicked off a session with that instance. But ngl you could've just as easily started another independent telnet session in another shell instance to 127.0.0.1 20001. Same vibe, different door. 💅

Also, when you're done with the vpcs session, you can bounce either with the disconnect command, or with the key combo Ctrl+X. And here's the tea — if you've got nested rlogin sessions, Ctrl+X takes you back to the hypervisor, but disconnect takes you back one level in the nesting. Not the same thing, don't mix them up. 🙈

💀 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. Yeah. That one hurts. 😭

Please send problems, bugs, questions, desirable enhancements, patches etc to the author. They want the mail, fr fr.

👑 AUTHOR 👑

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

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.

And that's the whole page, bestie — this was VPCS(1), version 0.8, dated 2013-12-16. Go forth and sim some virtual PCs. Slay. ✨🎀

📦 where this page comes from