CipherSpace Virtual Router

CipherSpace Virtual Router is based on OpenNebula Virtual Router (http://docs.opennebula.org/4.8/administration/networking/router.html) with some modifications plus OpenVPN. It is meant to be used as:

• Router (masquerade)
• DHCP server
• DNS server
• RADVD server
• Port forwarding server
• Bastion host for SSH tunnels
• OpenVPN server

CipherSpace Virtual Router allows using VMs which are not contextualized.

The virtual router image is non-persistent and takes its entire configuration from the contextualization script. Default VM size is 256MB RAM, 0.5 CPU and 1 vCPU. You can install it from the Appmarket.

When using DHCP or OpenVPN make sure IP spoofing and MAC spoofing protections are turned off for the internal network. Otherwise it will not work.

Contextualization Options

Appliance can be configured with 1 or 2 network interfaces. With 1 network interface it can be used only as DHCP or RADVD server.

• TEMPLATE - this is required. Otherwise most of the other functionality will not work. Usage:

TEMPLATE   = "$TEMPLATE"

• PRIVNET - private network. For example:

PRIVNET = "$NETWORK[TEMPLATE, NETWORK=\"<private_network_name>\"]"

• PUBNET - public network. For example:

PUBNET = "$NETWORK[TEMPLATE, NETWORK=\"<public_network_name>\"]"

• RADVD - enables or disabled RADVD server. Possible values are YES and NO. For example

RADVD = "NO"

• DHCP - enables or disabled DHCP server. Possible values are YES and NO. For example

DHCP = "YES"

• DNS - list of DNS servers to use in DHCP leases. If not specified DHCP server will use VMs private network IP address. For example:

DNS = "10.1.1.1 10.2.2.2"

• SEARCH - DNS search option. For example:

SEARCH = "zh4.cipherspace.net"

• NTP_SERVER - IP of the NTP server. The DHCP server will be configured to serve the NTP parameter to its leases. For example:

NTP_SERVER = "10.0.0.10"

• FORWARDING - list of forwarding rules separated by spaces. Syntax:

[[protocol:]route_port:]destination:vm_port

protocol is not validated but it only makes sense to use tcp or udp.Default is tcp. If router_port is omitted too then port vm_port on the router will be forwarded to vm_port on the VM. For example:

FORWARDING = "udp:8888:10.0.0.10:53 8080:10.0.0.10:80 10.0.0.10:22"

udp:8888:10.0.0.10:53	Forward UDP port 8888 on the router to port 53 on 10.0.0.10.
8080:10.0.0.10:80	Forward TCP port 8080 on the router to port 80 on 10.0.0.10.
10.0.0.10:22	Forward TCP port 22 the router to port 22 on 10.0.0.10.

• ROOT_PASSWORD - base64 encoded root password hash. For example one can use the following command:

openssl passwd -1 | base64

• SSH_PUBLIC_KEY - single line, base64 encoded list of SSH keys to be set as root's authorized_keys. That is the Public key field in Context->Network & SSH. This is not a custom field. The way scripts are implemented they cannot parse parameters which contain 'new line' character. Because of that CipherSpace Virtual Router expects the value of SSH_PUBLIC_KEY to be a single base64 encoded string. That way we can pass multiple SSH keys. To generate the string you can use command like this:

cat <pub_key1> <pub_key2> ... <pub_keyN> | base64 | paste -s -d '\0' -

• SSHD - if set to YES and SSH_PUBLIC_KEY is set, then sshd will be launched. The idea is that Virtual Router VMs will not need active maintenance thus sshd does not need to be on all the time. If SSH_PUBLIC_KEY is set keys will be installed for root regardless of whether SSHD is enabled or not. That way one can login on the console and launch sshd if required. Command for Apline Linux is:

rc-service sshd start

• OPENVPN - controls whether OpenVPN should be started or not. If OPENVPN_CA_CERT, OPENVPN_SERVER_CERT and OPENVPN_SERVER_KEY are defined openvpn is configured but it is only launched if OPENVPN is set to YES. Please note that when image is instantiated and openvpn is configured it will take several minutes, depending on allocated CPU, to boot because VM is generating DH 2048 bit parameters file.
• OPENVPN_CA_CERT - single line, PEM formatted, base64 encoded, Certification Authority certificate. That is the certificate used to sign OPENVPN_SERVER_CERT and all client certificates. Use the following command to encode:

cat ca.crt | base64 | paste -s -d '\0' -

• OPENVPN_SERVER_CERT - single line, PEM formatted, base64 encoded, server certificate.

• OPENVPN_SERVER_KEY - single line, PEM formatted, base64 encoded, server key

• OPENVPN_TA_KEY - optional but highly recommended, single line, PEM formatted, base64 encoded, preshared key to use with --tls-auth. This features adds "extra protection" to the TLS channel by requiring that incoming packets have a valid signature generated using the PSK key. Key must be set on both server and client. If this key is ever changed, it must be changed on all peers at the same time.

• OPENVPN_REVOKED - optional, single line, base64 encoded content of a file containing revoked certificates.

• OPENVPN_INT_NET - Network to be used for communication between the server and the clients. It has to be different from the internal OpenNebula network and client's network. Is omitted it default to 10.255.255.0. It is good idea to use different networks especially in one client setup. That way one can have multiple tunnels at the same time if destination networks don't overlap of course.

• OPENVPN_INT_NETMASK - Network mask for the network between the server and the clients. Defaults to 255.255.255.0. Warning: OpenVPN is very picky. It will complain and it will not start if netmask zeros out any bit from the network. For example: net 10.1.1.1 netmask 255.255.255.0 will not work. One needs to use: net 10.1.1.0 netmask 255.255.255.0

• OPENVPN_MAX_CLIENTS - Maximum number of simultaneously connected users. It defaults to 3. Tests showed that is a good number for the default size VM.

Please follow OpenVPN Key Management guide to generate keys.

CipherSpace Virtual Router can be used as a bastion host to build ssh tunnels. This is controlled by the following context variables:

• TUNNEL_USER - user name. It must not exist. If user exists it will not be reconfigured. That is to prevent messing up system users. User shell is set to /bin/false.

• TUNNEL_USER_SSH_PUBLIC_KEY - single line, base64 encoded, list of keys to install in authorized_keys file. Since it can can be multi-line it has to be formatted the same way as SSH_PUBLIC_KEY.

• TUNNEL_USER_KEY_RESTRICTIONS - optional string that goes before the key in authorized_keys file. Defaults to "no-pty,no-agent-forwarding,no-X11-forwarding,no-user-rc". Even though user shell is set to /bin/false one must be careful what goes in this variable.