[[TOC(Documentation/C*, depth=3)]] = How to get started = First, you will need an ORBIT account. Please check the [wiki:Documentation/BUsagePolicy usage policy] if you are eligible. Typically, in order to get an account, one would have to [http://www.orbit-lab.org/userManagement/register register for a user account] and get it approved by the PI in charge of the project/institution they wish to be part of. If the particular institution is not available on the user account registration page, the appropriate PI can [http://www.orbit-lab.org/userManagement/orgReg register for an institutional account]. '''IMPORTANT:''' Once you have an account, [wiki:Documentation/bAccountManagement/DSSHConf configure your ssh client] to use key based authentication. '''Note: this demo shows the basic use of the testbed, i.e. how to provision resources using the orbit management framework, and how to use the resources for your experiment. The example "experiment" is an extended exercise meant to demonstrate some of the skills useful in using the testbed. Users who are already comfortable with a linux command line environment can skip this step.''' These instructions assume basic familiarity with a command line environment. If you are feeling lost, [https://ubuntu.com/tutorials/command-line-for-beginners#1-overview this tutorial] is a good place to start. == Six Steps == A typical experiment requires the following six steps: == 1. Create a resource reservation == The user needs a set of nodes/resources from a domain to run the experiment on. [[Include(Documentation/Short/CreateRes)]] '''For the rest of this tutorial we will assume that the reservation was made for the sb1 domain.''' == 2. Login into reserved domain == After you receive the reservation confirmation email, you can access the reserved domain by SSH'ing to the corresponding domain console. [[Include(Documentation/Short/Login2)]] == 3. Load an image onto the nodes == Prior to executing the "Hello World" experiment, users need to install a system image on the hard disks of the nodes. For this tutorial we will use '''baseline20.04.ndz'''. This image is built on top of '''Ubuntu 20.04''', and is pre-configured with a minimal set of required software so that experimenters can customize it for their needs. For information about the contents of baseline images, check here: [wiki:/Software software] / [wiki:/Hardware hardware]. The imaging process will turn the nodes off after completing imaging. [[Include(Documentation/Short/LoadImage)]] === Provision SB1 nodes === So, for our experiment on sb1, run the following: {{{ username@console:~$ omf stat -t all username@console:~$ omf tell -t all -a offh username@console:~$ omf load -t all -i baseline20.04.ndz }}} We are using `all` for our set of nodes here because there are only two nodes in sb1. For a larger domain like grid, you should specify a list of specific nodes, like `node1-1,node2-1,node8-8`. '''Do not turn on all of the nodes in grid! ''' == 4. Turn the nodes on == At this point the nodes' disks are imaged with the ''baseline'' image and need to be turned back on before proceeding. Use the `omf tell` command to turn the nodes on and give them a couple of minutes to boot, then check their status with `omf stat`. == 5. Run your experiment == In this example, our "experiment" will be to use one node as a wireless access point, which the other node will connect to. This is meant to demonstrate the basic way in which experimenters interact with testbed resources, along with some basic skills which will be useful during your use of the testbed. === Preliminary steps === 1. First, we need to ssh from the console to the node. You will operate as the root user on the nodes, so run `ssh root@node1-1` to connect to node1-1, for example. You may want to open a second terminal with another connection to console.sb1.orbit-lab.org so that you can simultaneously ssh to node1-2 and run these commands in parallel. Before we set up the access point, we want to make sure that the wireless interfaces on both nodes are on. By default, wireless interfaces on ORBIT nodes are disabled to reduce RF noise for experiments. On both nodes, run `ip a` to list the current network interfaces. You should see something like {{{ 1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 inet 127.0.0.1/8 scope host lo valid_lft forever preferred_lft forever inet6 ::1/128 scope host valid_lft forever preferred_lft forever 2: DATA1: mtu 1500 qdisc fq_codel state UP group default qlen 1000 link/ether 70:8b:cd:bc:82:8d brd ff:ff:ff:ff:ff:ff inet6 fe80::728b:cdff:febc:828d/64 scope link valid_lft forever preferred_lft forever 3: CTRL: mtu 1500 qdisc fq_codel state UP group default qlen 1000 link/ether 70:8b:cd:bc:82:8c brd ff:ff:ff:ff:ff:ff inet 10.11.1.1/16 brd 10.11.255.255 scope global dynamic CTRL valid_lft 5170sec preferred_lft 5170sec inet6 fe80::728b:cdff:febc:828c/64 scope link valid_lft forever preferred_lft forever }}} These are the default wired interfaces available on all ORBIT nodes: CTRL is the interface that is used to connect to the nodes from the console. It is also the interface over which internet traffic is routed. '''Note: be very careful when modifying the CTRL interface-- you may make your node inaccessible over ssh.''' You can also see the DATA interface. This interface is meant to be configured as part of experiments, which is why it does not have an IP address. If we run `iw list` to list wireless interfaces, we should see that there are currently no wireless interfaces. First we must check what wireless devices are present to determine which driver module to load. Run `lshw -c network` to list network devices available on the node. You should see in the output that there is an AR928X wireless network card. For this particular card, we need to run the following to load the proper driver: `modprobe ath9k`. Now, we should be able to see the wireless interface in the output of the `ip` and `iw` commands: {{{ 1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 inet 127.0.0.1/8 scope host lo valid_lft forever preferred_lft forever inet6 ::1/128 scope host valid_lft forever preferred_lft forever 2: DATA1: mtu 1500 qdisc fq_codel state UP group default qlen 1000 link/ether 70:8b:cd:bc:82:8d brd ff:ff:ff:ff:ff:ff inet6 fe80::728b:cdff:febc:828d/64 scope link valid_lft forever preferred_lft forever 3: CTRL: mtu 1500 qdisc fq_codel state UP group default qlen 1000 link/ether 70:8b:cd:bc:82:8c brd ff:ff:ff:ff:ff:ff inet 10.11.1.1/16 brd 10.11.255.255 scope global dynamic CTRL valid_lft 6797sec preferred_lft 6797sec inet6 fe80::728b:cdff:febc:828c/64 scope link valid_lft forever preferred_lft forever 4: wlp3s0: mtu 1500 qdisc noop state DOWN group default qlen 1000 link/ether 00:15:6d:84:3f:20 brd ff:ff:ff:ff:ff:ff }}} Make sure you have enabled the wireless interface on both nodes in the sandbox. Now, use the `ip` command to bring up the new wireless interface: {{{ root@node1-1:~# ip link set wlp3s0 up }}} The interface is now running, but it isn't connected to any networks. We can use either node to scan for the available networks, to ensure that we don't start a new network with the same ssid as an existing one. Running `iw dev wlp3s0 scan` will print out all available information about all available networks (make sure to substitute in the name of your wireless interface if it is different). To find the exact information we're looking for, we can use the grep utility: `iw dev wlp3s0 scan | grep SSID`. Grep has many capabilities, but we can see it's simplest use case here: it outputs lines containing a search string. We have also taken advantage of the pipe utility provided by the linux command line to feed the output of one command into another. === Set up Access Point === We will use node1-1 as the access point. 1. Before we install anything, we need to get an updated list of the available software by running `apt update`. Now install hostapd and dnsmasq on node1-1: {{{ root@node1-1:~# apt install hostapd dnsmasq }}} You'll see some error messages because dnsmasq is unable to start automatically. That's ok for now. 2. Now we need to configure the services we just installed. We'll start with hostapd, the service that creates the access point. Create a directory called `hostapd` in the `/etc` directory by running `mkdir /etc/hostapd`. Open a file called `hostapd.conf` in `/etc/hostapd/` using your editor of choice. Nano is a good option for beginners: {{{ root@node1-1:~# nano /etc/hostapd/hostapd.conf }}} Note the commands listed at the bottom of the nano interface, especially exit and write out (save to file). The `^` in the command stands for control. So to save your changes and exit, you would press CTRL+O then CTRL+X. Enter the following into the new file, making sure to change the first line if your wireless interface has a different name: {{{ interface=wlp3s0 logger_syslog=-1 logger_syslog_level=2 logger_stdout=-1 logger_stdout_level=2 ctrl_interface=/var/run/hostapd ctrl_interface_group=0 ssid=hello-wireless hw_mode=g channel=1 beacon_int=100 dtim_period=2 max_num_sta=20 rts_threshold=-1 fragm_threshold=-1 auth_algs=1 ignore_broadcast_ssid=0 wpa=2 wpa_passphrase=t0pS3cr3t wpa_key_mgmt=WPA-PSK wpa_pairwise=CCMP }}} These parameters are mostly default values, but note in particular the ssid name and passphrase. We will need these to connect to the network. For an explanation of what these parameters do, you can read the example file `/usr/share/doc/hostapd/examples/hostapd.conf`. 3. Now we will set up the configuration for dnsmasq, which is used to provide ip addresses to clients that connect to the access point. A configuration file already exists at /etc/dnsmasq.conf, although it doesn't have any configuration to start. Open the file to add the following lines: {{{ bogus-priv bind-interfaces listen-address=192.168.100.1 dhcp-range=192.168.100.50,192.168.100.150,2h }}} This is a very minimal configuration, but it should be all we need. 4. You can see we're telling dnsmasq to listen on the ip address 192.168.100.1, but we haven't put that address on our wireless interface yet. We can do that with the following command: {{{ root@node1-1:~# ip addr add 192.168.100.1/24 dev wlp3s0 }}} 5. Now we can start the services. We have to first enable hostapd, which is disabled after you first install it. {{{ root@node1-1:~# systemctl unmask hostapd.service root@node1-1:~# systemctl start hostapd.service root@node1-1:~# systemctl start dnsmasq.service }}} === Connect to Access Point === 1. First, verify that you can see the "hello-wireless" network from node1-2 by running the prior command to scan for interfaces and grepping for SSID. 2. We'll use a utility called wpa_supplicant to connect to the access point. After running `apt update`, run the following to install it: {{{ root@node1-2:~# apt install wpasupplicant }}} 3. To set up wpa_supplicant to connect to "hello-wireless", we'll use its built-in utility to modify the configuration file: {{{ root@node1-2:~# wpa_passphrase "hello-wireless" "t0pS3cr3t" > /etc/wpa_supplicant.conf }}} 4. Now we can connect to the network: {{{ root@node1-2:~# wpa_supplicant -B -i wlp3s0 -c /etc/wpa_supplicant.conf }}} 5. We need to manually request an ip address after connecting: {{{ root@node1-2:~# dhclient wlp3s0 }}} 6. Verify that you can see an ip address in the 192.168.100.X ip space on the wireless interface. You should also be able to use the ping utility to test connectivity to node1-1 over the wireless interface: {{{ root@node1-2:~# ping 192.169.100.1 }}} 7. As a final test , we can bring down the wired interfaces on node1-2 and ssh to it from node1-1 over the wireless network. Use the ip command to turn off first DATA1, then CTRL. You'll use the same command you used to bring the interfaces up, except now you'll use `down` instead of `up`. Make sure to use the correct interface names. After you bring down CTRL, your ssh connection will become unresponsive. Now, from node1-1, ssh to root at the ip address that node1-2 had on the wireless interface. From there, you can bring the interfaces back up. This concludes the demo experiment. == 6. (optionally) Save the node image == After you have invested time in customizing one of the baseline images for your experiment, you may want to save your work as a custom image for you to start with during your next reservation. This must be done '''before the end of your time slot'''-- saving an image can take a long time depending on the amount of additional content you have added. Make sure you budget time in your reservation to save your work. '''Note that these instructions are here as a reference. There is no need to save the example experiment.''' [[Include(Documentation/Short/SaveImage2)]] == Where to go from here == If you are still unsure what Orbit is, please read the [wiki:FAQ FAQ] and check other [wiki:Tutorials tutorials].