From 6a442e9cb803dfc56bc7774bd677f712d0a1b32f Mon Sep 17 00:00:00 2001 From: "Manuel Amador (Rudd-O)" Date: Wed, 12 Oct 2016 17:03:13 +0000 Subject: [PATCH] Documentation improvements. --- README.md | 87 ++------------------- doc/Setting up an SSH server.md | 114 ++++++++++++++++++++++++++++ doc/Setting up your first server.md | 84 ++++++++++++++++++++ 3 files changed, 206 insertions(+), 79 deletions(-) create mode 100644 doc/Setting up an SSH server.md create mode 100644 doc/Setting up your first server.md diff --git a/README.md b/README.md index ae6f486..2514707 100644 --- a/README.md +++ b/README.md @@ -51,89 +51,15 @@ exactly the same Qubes OS user experience you are used to. This is all, of course, opt-in, so the standard Qubes OS network security model remains in effect until you decide to share network servers. -##Usage +##How to use this software Once installed (see below), usage of the software is straightforward. +Here are documents that will help you take advantage of Qubes +network server: -To illustrate, we'll proceed with an example VM `httpserver` which -is meant to be a standalone VM that contains files, being served by -a running HTTP server (port 80) within it. This VM is attached to -a ProxyVM `server-proxy`, which in turn is connected to a NetVM -`sys-net`, with IP address `192.168.1.4` on a local network -`192.168.1.0/24`. Our goal will be to make `httpserver` accessible -to your laptop on the same physical network, which we'll assume has -IP address `192.168.1.8`. +* [Setting up your first server](doc/Setting up your first server.md) +* [Setting up an SSH server](doc/Setting up an SSH server.md) -###Assign a static address - -First step is to assign an address — let's make it `192.168.1.6` — -to `httpserver`: - -``` -qvm-static-ip -s httpserver static_ip 192.168.1.6 -``` - -###Restart VM - -Due to limitations in this release of the code, you must power off -the `httpserver` VM and then power it back on. - -###Set firewall rules on VM - -Launch the Qubes Manager preferences window for the `httpserver` VM. -Go to the *Firewall rules* tab and select *Deny network access -except...* from the top area. *Allow ICMP traffic* but deny -*DNS queries*. - -Finally, add a new network rule (use the plus button). On the -*Address* box, you're going to write `from-192.168.1.8`. Select -the *TCP* protocol, and type `80` on the *Service* box. Click OK. - -Note the trick here — any address whose text begins with -`from-` gets transformed into an incoming traffic rule, as opposed -to the standard rules that control only outbound traffic. - -**Security note**: the default "allow all" firewall leaves all ports -of the VM accessible to the world. To the extent that you can avoid -it, do not use the "allow all" firewall setting at all. - -Back on the main dialog, click *OK*. - -###That's it! - -You'll be able to ping, from your laptop, the address `192.168.1.6`. -You will also be able to point your browser at it, and it will -render the served pages from the HTTP server running directly on -`httpserver`. - -Save from ICMP, no other port or protocol will be allowed for -inbound connections. - -You'll also note that `httpserver` has received no permission to -engage in any sort of outbound network traffic. - -###Inter-VM network communication - -This software isn't limited to just letting network servers be -accessible from your physical network. VMs can talk among each -other too. Simple instructions: - -* Set up a static IP address for each VM. -* Set up the appropriate rules to let them talk to each other. - -VMs so authorized can talk to each other over the network, -even when they do not share a ProxyVM between them, of course, -so long as their ProxyVMs share the same NetVM. - -###Disabling network server - -Two-step process. Step one: - -``` -qvm-static-ip -s httpserver static_ip none -``` - -Step two: power the VM off, then start it back up. ##Installation @@ -144,6 +70,9 @@ Installation is extremely easy: * Copy the prepared RPM to the dom0 of your Qubes OS machine. * Install the RPM with `rpm -ivh`. +* Restart Qubes Manager, if it is running. + (Right-click on its notification icon, select *Exit*, then + relaunch it from the *System* menu.) Qubes OS does not provide any facility to copy files from a VM to the dom0. To work around this, you can use `qvm-run`: diff --git a/doc/Setting up an SSH server.md b/doc/Setting up an SSH server.md new file mode 100644 index 0000000..58cc4e1 --- /dev/null +++ b/doc/Setting up an SSH server.md @@ -0,0 +1,114 @@ +# Setting up an SSH server + +This tutorial will teach you how to set up an SSH server on your Qubes network server. + +We assume: + +1. That you have a desktop or laptop *manager* machine, from which you desire to manage a Qubes OS server. +2. That you have a Qubes OS *server*, which you want to manage. +3. That both machines share a physical network link (e.g. Wi-Fi or Ethernet). + +## Set up Qubes network server + +First of all, [install Qubes network server](https://github.com/Rudd-O/qubes-network-server#installation) on your Qubes OS server. + +## Set up needed VMs + +You'll need three VMs on the network server: + +1. A NetVM which will be attached to the network interface mentioned above. + For the purposes of this example, we'll call this `exp-net`. +2. A ProxyVM which will be attached to the NetVM. + This we'll call `exp-firewall`. +3. A StandaloneVM which will be attached to the ProxyVM. The role of this + machine is to give you control over `dom0` and other VMs on the system. + This we'call `exp-manager`. + +Create them if you do not already have them. Once you have created them, +start the StandaloneVM `exp-manager` you created, and then verify that you +can ping your manager machine from it. + +Power off `exp-manager` when your test is complete. + +## Set static address on `exp-manager` + +On your server's `dom0`, run the command: + +``` +qvm-static-ip -s exp-manager static_ip x.y.z.w +``` + +`x.y.z.w` must be an IP address available on the same network that both +your `exp-net` and your manager machine share. + +Power `exp-manager` back on, and verify that you can still ping your +manager machine from it. + +Verify that you can ping the new IP address you gave to `exp-manager` +from your manager machine. This should work fine. + +## Harden the firewall on `exp-manager` + +At this point, `exp-manager` is accessible on your network, so it's best +to set up a firewall rule permitting only SSH access from the manager +machine, and denying all other access to anyone. + +If you are new to firewall rules in Qubes, [check out this quite +good overview of them](https://www.qubes-os.org/doc/qubes-firewall/). + +Launch the Qubes Manager preferences window for the `exp-manager` VM. +Go to the *Firewall rules* tab and select *Deny network access +except...* from the top area. + +Add a new network rule (use the plus button). On the *Address* box, +you're going to write `from-a.b.c.d`, where `a.b.c.d` is the IP address +of your manager machine. Select the *TCP* protocol, and type `22` +(the SSH port) on the *Service* box. Click OK. + +([See the documentation for qubes-network-server](https://github.com/Rudd-O/qubes-network-server) +to understand more about firewalling rules in Qubes network server.) + +Back on the main dialog, click *OK*. + +## Enable and start SSH on the `exp-manager` VM + +In a terminal window of `exp-manager`, run: + +``` +sudo systemctl enable sshd.service +sudo systemctl start sshd.service +``` + +This will start the OpenSSH server on the `exp-manager` VM. + +Test that you can connect via SSH from the manager machine to +the `exp-manager` VM. You will not be able to log in, because +no password is set up, but we will fix that shortly. + +## Set up SSH authentication + +On the `exp-manager` VM, set a password on the `user` user: + +``` +sudo passwd user +``` + +On the manager machine, copy your SSH public key to `exp-manager`: + +``` +ssh-copy-id user@x.y.z.w +``` + +This will prompt you for the password you set up. Enter it. + +Now kill the `user` password on `exp-manager`: + +``` +sudo passwd -d user +sudo passwd -l user +``` + +Good news! You can now remotely log in, from your manager machine, +to your Qubes OS server. + +You can also [enable remote management of your Qubes network server](https://github.com/Rudd-O/ansible-qubes/tree/master/doc/Remote management of Qubes OS servers.md). diff --git a/doc/Setting up your first server.md b/doc/Setting up your first server.md new file mode 100644 index 0000000..bdcb2b2 --- /dev/null +++ b/doc/Setting up your first server.md @@ -0,0 +1,84 @@ +# Setting up your first server under Qubes network server + +To illustrate, we'll proceed with an example VM `httpserver` which +is meant to be a standalone VM that contains files, being served by +a running HTTP server (port 80) within it. This VM is attached to +a ProxyVM `server-proxy`, which in turn is connected to a NetVM +`sys-net`, with IP address `192.168.1.4` on a local network +`192.168.1.0/24`. Our goal will be to make `httpserver` accessible +to your laptop on the same physical network, which we'll assume has +IP address `192.168.1.8`. + +##Assign a static address + +First step is to assign an address — let's make it `192.168.1.6` — +to `httpserver`: + +``` +qvm-static-ip -s httpserver static_ip 192.168.1.6 +``` + +##Restart VM + +Due to limitations in this release of the code, you must power off +the `httpserver` VM and then power it back on. + +##Set firewall rules on VM + +If you are new to firewall rules in Qubes, [check out this quite +good overview of them](https://www.qubes-os.org/doc/qubes-firewall/). + +Launch the Qubes Manager preferences window for the `httpserver` VM. +Go to the *Firewall rules* tab and select *Deny network access +except...* from the top area. *Allow ICMP traffic* but deny +*DNS queries*. + +Finally, add a new network rule (use the plus button). On the +*Address* box, you're going to write `from-192.168.1.8`. Select +the *TCP* protocol, and type `80` on the *Service* box. Click OK. + +Note the trick here — any address whose text begins with +`from-` gets transformed into an incoming traffic rule, as opposed +to the standard rules that control only outbound traffic. + +**Security note**: the default "allow all" firewall leaves all ports +of the VM accessible to the world. To the extent that you can avoid +it, do not use the "allow all" firewall setting at all. + +Back on the main dialog, click *OK*. + +##That's it! + +You'll be able to ping, from your laptop, the address `192.168.1.6`. +You will also be able to point your browser at it, and it will +render the served pages from the HTTP server running directly on +`httpserver`. + +Save from ICMP, no other port or protocol will be allowed for +inbound connections. + +You'll also note that `httpserver` has received no permission to +engage in any sort of outbound network traffic. + +##Inter-VM network communication + +This software isn't limited to just letting network servers be +accessible from your physical network. VMs can talk among each +other too. Simple instructions: + +* Set up a static IP address for each VM. +* Set up the appropriate rules to let them talk to each other. + +VMs so authorized can talk to each other over the network, +even when they do not share a ProxyVM between them, of course, +so long as their ProxyVMs share the same NetVM. + +##Disabling network server + +Two-step process. Step one: + +``` +qvm-static-ip -s httpserver static_ip none +``` + +Step two: power the VM off, then start it back up.