1. kathara-vstart(1)
  2. Kathara manual
  3. kathara-vstart(1)

NAME

kathara-vstart - Start a new Kathara device

SYNOPSIS

kathara vstart -n DEVICE_NAME
[-h] [--noterminals | --terminals | --privileged | --num_terms NUM_TERMS]
[--eth <N:CD[/MAC_ADDR]> [<N:CD[/MAC_ADDR]> ...]]
[-e [EXEC_COMMANDS [EXEC_COMMANDS ...]]] [--mem MEM]
[--cpus CPUS] [-i IMAGE] [--no-hosthome | --hosthome] [--xterm XTERM] [--print] [--bridged]
[--port <[HOST:]GUEST[/PROTOCOL]> [<[HOST:]GUEST[/PROTOCOL]> ...]] [--env ENV [ENV ...]] [--sysctl SYSCTL [SYSCTL ...]] [--shell SHELL]

DESCRIPTION

Start a new device named DEVICE_NAME. Names of devices must be unique for each user. Yet, different users can run devices having the same name.

Without providing options, vstart starts a device whose configuration reflects the defaults stored inside the kathara.conf(5) file. The options described below can be used to adjust the features of a device upon starting it.

Notice: unless differently stated, command line arguments (DEVICE_NAME) and option arguments (e.g., names of collision domains) should not contain space characters. Not complying to this causes vstart to raise an error.

OPTIONS

-h, --help
Show a help message and exit.
--noterminals
Start the device without opening a terminal window.

Overrides the default setting specified in kathara.conf(5) file.

--terminals
Start the device opening its terminal window.

Overrides the default setting specified in kathara.conf(5) file.

--privileged
Start the devices in privileged mode. MUST BE ROOT FOR THIS OPTION.
-n DEVICE_NAME, --name DEVICE_NAME
Name of the device to be started.
--eth <N:CD[/MAC_ADDR]> [<N:CD[/MAC_ADDR]> ...]
Set a specific interface on a collision domain.

CD: The name of the collision domain to which the specified interface must be connected. Note that the name of the collision domain must not contain spaces (" "), commas (",") and dots (".").

/MAC_ADDR: An optional parameter to specify the MAC address of the interface (MAC address must be in the format XX:XX:XX:XX:XX:XX). If MAC_ADDR is not provided, Kathara will assign a random one.

Equip the device with a network interface. N is a positive integer starting from 0. The network interface will be attached to a (virtual) collision domain whose name is CD. Attaching interfaces of different devices to the same collision domain allows them to exchange network traffic. N should be declared as a sequential number, starting from 0; if any intermediate number is missing an exception is raised.

-e [EXEC_COMMANDS [EXEC_COMMANDS ...]], --exec [EXEC_COMMANDS [EXEC_COMMANDS ...]]
Execute a specific command in the device during startup.

Run a specific command inside the device during the startup phase. EXEC_COMMANDS are shell commands executed with the shell defined in --shell or with the default shell defined in kathara.conf(5).

--mem MEM
Limit the amount of RAM available for this device.

Set the amount of available RAM inside the device to MEM. If it is not set, the device could use as much RAM as the Docker daemon can use. If you set this option, the minimum allowed value is 4m (4 megabyte).
This option takes a positive integer, followed by a suffix of "b", "k", "m", "g", to indicate bytes, kilobytes, megabytes, or gigabytes.

--cpus CPUS
Limit the amount of CPU available for this device.

Set the amount of available CPU inside the device to CPUS. If it is not set, the device could use as much CPU as the Docker daemon can use.
This option takes a positive float, ranging from 0 to the max number of logical CPUs of the host. For instance, if the host device has two CPUs and you set --cpus 1.5, the container is guaranteed at most one and a half of the CPUs.

-i IMAGE, --image IMAGE
Run this device with a specific Docker Image.

The specified Docker Image could be in the local repository or on the Docker Hub. Overrides the default setting specified in kathara.conf(5) file.

--no-hosthome, -H
Do not mount /hosthome directory inside devices.

Do not mount the home directory of the current user inside devices. This is the default specified in kathara.conf(5) file.

--hosthome
Mount /hosthome directory inside devices.

Mount the home directory of the current user inside devices in the special directory /hosthome. This option makes the host filesystem accessible from inside devices, overriding the default setting specified in kathara.conf(5) file.

--xterm XTERM, --terminal-emu XTERM
Set a different terminal emulator application (Unix only).

As an example: gnome-terminal(1). Overrides the default setting specified in kathara.conf(5) file. This option is ignored if used in conjunction with --noterminals or if open_terminals is set to false.

--print, --dry-mode
Check if the device parameters are correct (dry run).
--bridged
Add a bridge interface to the device.

Connect the device to the host network by adding an additional network interface (will be the last one). This interface will be connected to the host network through a NAT connection and will receive its IP configuration automatically via DHCP.

--port <[HOST:]GUEST[/PROTOCOL]> [<[HOST:]GUEST[/PROTOCOL]> ...]
Map localhost port HOST to the internal port GUEST of the device for the specified PROTOCOL. The syntax is [HOST:]GUEST[/PROTOCOL].

If HOST port is not specified, default is 3000. If PROTOCOL is not specified, default is tcp. Supported PROTOCOL values are: tcp, udp, or sctp. For instance, with this command you can map host's port 8080 to device's port 80 with TCP protocol: --port "8080:80/tcp".

--sysctl SYSCTL [SYSCTL ...]
Set a sysctl option for the device. Only the net. namespace is allowed to be set.
--env ENV [ENV ...]
Set an environment variable for the device. The format is: ENV_NAME=ENV_VALUE.
--num_terms NUM_TERMS
Choose the number of terminals to open for the device.
--shell SHELL
Set the shell (sh, bash, etc.) that should be used inside the device.

The requested shell must be installed inside the device. Overrides the default setting specified in kathara.conf(5) file.

EXAMPLES

kathara vstart -n pc1

Start a new device named pc1.

kathara vstart -n mypc1 -i my-image --mem 128m

Start a new device named mypc1. The device will run using local image my-image and will be equipped with 128 MB of RAM.

kathara vstart -n producer --eth 0:A
kathara vstart -n consumer --eth 0:A

Start two devices named producer and consumer, which will be able to exchange data with each other by using their network interfaces eth0. Such interfaces will have to be configured with an IP address before the communication can actually take place.

kathara vstart -n router --bridged --eth 0:A

Start a new device named router. The device will have two network interfaces. Interface eth0 will be attached to the virtual collision domain named A and will have to be configured by hand inside the device (for example, by using ifconfig). Interface eth1 will be connected to the host network through a NAT connection.

kathara vstart -n test --eth 0:A 1:B --print

Instead of actually starting a device, check if the passed device parameters are correct.

kathara vstart -n terminal_test --xterm gnome-terminal

Start a device named terminal_test which uses the gnome-terminal terminal.

REPORTING BUGS

Report bugs opening an issue on the official GitHub repository where the development and maintenance is primarily done.
Issues which are security relevant should be disclosed privately to the Kathara mailing list. You do not have to be subscribed to the list to send a message there.
When reporting a bug, remember to write used commands, eventually attach your network scenario, and include the output of kathara-check(1) in order to make possible to reproduce the bug.

AUTHORS

Kathara was born from Netkit. Its first version was developed by Gaetano Bonofiglio and Veronica Iovinella. Currently it is mantained by Mariano Scazzariello, Tommaso Caiazzi and Lorenzo Ariemma.

People involved also include:

Copyright © 2017-2024 License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

SEE ALSO

kathara(1), kathara-vclean(1), kathara-vconfig(1), kathara.conf(5)

  2. April 2024
  3. kathara-vstart(1)