From fbf86f5aa83191678c652b2c0fd62b7e36332eea Mon Sep 17 00:00:00 2001 From: alban Date: Thu, 24 Sep 2020 14:34:44 +0200 Subject: [PATCH] [fix] more doc + fixes --- README.md | 233 +++++++++++++++++++++++++++++++++++++++++++++ build.json | 1 - files/root/.bashrc | 79 --------------- 3 files changed, 233 insertions(+), 80 deletions(-) create mode 100644 README.md delete mode 100644 files/root/.bashrc diff --git a/README.md b/README.md new file mode 100644 index 0000000..a5ae413 --- /dev/null +++ b/README.md @@ -0,0 +1,233 @@ +# LJ Packer + +### Welcome to LJ Packer, [LJ](https://git.interhacker.space/teamlaser/LJ) software's virtual machine images provider. + +#### Errr... Sorry but what is this "LJ" thing already? +* LJ is used to command multiple _LASERS_ via a _CENTRAL SERVER_ +* _CENTRAL SERVER_ exchanges data with _LASERS_ and _POINTS GENERATORS_ on a Local Area Network (LAN) +* _LASERS_ use _[ETHER-DREAMS](https://ether-dream.com/)_ interfaces to connect to _LAN_ +* _POINTS GENERATORS_ store their output in a _REDIS_ located on _CENTRAL SERVER_ + +**The images produced by this code provide _CENTRAL SERVER_ and _REDIS_, plus some help to configure _LAN_.** You will need _LASERS_ and _ETHER-DREAMS_ to get a fully working setup. + +## OK, but why? + +LJ is written in Python with lots of dependencies and can be a bit difficult to configure, hence the need for such bootable and easily (re)configured system images. + +**But be cautious, the images are not safe to run on the Internet AT ALL!** The SSH server is open for root login with a _**VERY**_ simple password: + +``` +root:laser +``` + +**Run the images produced with care on local / airtight networks.** + +# Images + +No official repository for images yet, but this is expected in the future. + +# Limitations + +All of this has been tested only on Debian 10 Buster. YMMV. + +# Crash course + +These instructions are for *building* images, see below to *run* images. + +You need to [install packer](https://www.packer.io/downloads) first, the syntax is valid with version 1.6+ + +**Compiling for qemu (recommanded):** + +``` +sudo apt install qemu qemu-kvm +git clone https://git.interhacker.space/teamlaser/lj-packer +cd lj-packer +# The "no-desktop" install +PACKER_LOG=1 sudo packer build -on-error=ask --only=teamlaser-lj build.json +# The "desktop" install +PACKER_LOG=1 sudo packer build -on-error=ask --only=teamlaser-lj-xfce build.json + +``` + +**Compile for LXC (not fully tested, should work):** +``` +sudo apt install lxc +PACKER_LOG=1 sudo packer build -on-error=ask --only=teamlaser-lj-lxc build.json +``` + +All the compilation should be automatic, and result with images in local directories (output, output) + +# Running in KVM + +All commands are given for terminal use and probably require root access. + +You will need to select one of the images from those: +``` +export IMAGE=packer-teamlaser-lj-xfce +export IMAGE=packer-teamlaser-lj +``` + + +## kvm:user : KVM with simple/no-LAN network + +**It is the simple solution, useful for fast testing the software.** +You will access the VM services through "virtual" localhost ports of your machine. +But the VM will not be able to exchange data on LAN. + + +### kvm:user Local Ports to VM ports + +Ports translations are done by adding 10000 to each VM service port. + +* 10022 SSH(22) +* 10080 HTTP(80) +* 10443 HTTPS(443) +* 16379 REDIS(6379) +* 16454 ARTNET(6454) +* 19001 WEBSOCKET(9001) + +So, to connect to the SSH server you will use the 10022 port on localhost. + +### kvm:user Booting + + +``` +# start the VM +sudo /usr/bin/qemu-system-x86_64 \ + -m 2048M -boot once=d \ + -machine type=pc,accel=kvm \ + -display gtk -vnc 127.0.0.1:6 \ + -name ${IMAGE}\ + -drive file=${IMAGE},format=qcow2 + -device virtio-net,netdev=user.0 \ + -netdev user,id=user.0,hostfwd=tcp::10022-:22,hostfwd=tcp::10080-:80,hostfwd=tcp::10443-:443,hostfwd=tcp::16379-:6379,hostfwd=tcp::6454-:6454,hostfwd=tcp::19001-:9001\ + +``` + +### kvm:user Connecting +``` +# Wait until ssh/login is available in the VM +# Type password "laser" i.e. "lqser" on AZERTY keyboards +ssh root@localhost -p10022 + +``` + +## kvm:bridge KVM with full network access + + +**It is a more complex solution, useful for real use of LJ with _LASERS_ on _LAN_.** +You will access the VM services through "virtual" localhost ports of your machine. +But the VM will not be able to exchange data on LAN. + +### kvm:bridge 1. Network configuration + +Here is the documentation on how to setup a bridge interface on your machine. +It is a bit complex, but follow the instructions and it should be fine... + +#### kvm:bridge 1.0. First some variables / names we will use +``` +# 0. Names / concepts +HOST The name used to define your laptop (or any other machine running qemu) +GUEST The name used to define the qemu virtual machine + +# 0. Variables +HOST_IF The variable for HOST's network interface, the one used for LAN. Ex: eth0, ens3 +HOST_IP The variable for HOST's IP address on the LAN. Ex: 192.168.1.20 +IP_RANGE The variable for size of a the subnet for your LAN. Ex: /24 +GUEST_IF The variable for GUEST's network interface. +GUEST_IP The variable for GUEST's IP address on the LAN. Ex: 192.168.1.21 +SU The sudo command required if not running as root + +## As an Example, here is a working configuration + +export HOST_IF=enx9cebe8ce6930 +export HOST_IP=192.168.1.99 +export IP_RANGE=/24 +export SU='sudo ' +``` + +#### kvm:bridge 1.1. Configuring HOST network interfaces +``` +# 1. Configure HOST: set up bridge over HOST_IF + +$SU ip l set dev ${HOST_IF} down +$SU brctl addbr br0 +$SU brctl addif br0 ${HOST_IF} +$SU ip tuntap add tap0 mode tap +$SU brctl addif br0 tap0 +$SU iptables -t nat -A POSTROUTING -o br0 -j MASQUERADE +$SU iptables -I FORWARD -i br0 -j ACCEPT +$SU ip l set dev ${HOST_IF} up +$SU ip l set dev br0 up +$SU ip l set dev tap0 up +$SU ip a add ${HOST_IP}${IP_RANGE} dev br0 +$SU sysctl net.ipv4.ip_forward=1 + +##troubleshooting: there must be NO ip address attached to $HOST_IF +$SU ip address show dev ${HOST_IF} | grep global || echo -e "\n\e[31mOops.... Remove all IP addresses from ${HOST_IF}! Use:\e[0m\n\n$SU ip address del (address/range shown above) dev ${HOST_IF}" +``` + +#### kvm:bridge 1.2. Booting the VM + +Notice how the `net` model changed: we have a MAC address and use the `tap` interface to exchange network packets. +``` +sudo /usr/bin/qemu-system-x86_64\ + -m 2048M -boot once=d\ + -machine type=pc,accel=kvm\ + -display gtk -vnc 127.0.0.1:6\ + -name ${IMAGE}\ + -drive file=${IMAGE},format=qcow2\ + -net nic,model=virtio,macaddr=00:00:00:00:00:01\ + -net tap,ifname=tap0\ +``` + +### kvm:bridge 1.3. Configuring GUEST's network + +This part may be more or less complex, as a DHCP server might automatically assign an IP address to your VM. + +Use the connection via login described below (1.4.2) : **a script will check the network connectivity on login.** + +According to its output, +* *you might be fine*: it will show an IP address which you can use to connect using standard protocols, i.e. SSH, HTTPS, etc. +* *you might be required to configure the network*. In such a case, you will be asked + * if you want to configure the network with a graphical tool. + This is an option for expert users. + It uses the nmtui (network-manager Terminal UI) interface. + Use and to forget to your interface + * to provide the GUEST_IP/RANGE and the GUEST_GW to use. + * GUEST_IP/RANGE are depending on your HOST_IP in the LAN + * GUEST_GW is your HOST_IP + * Also, can do things by yourself with the following commands: + ``` + ip address add ${GUEST_IP}/${IP_RANGE} dev ${GUEST_IF} + ip route add default via ${HOST_IP} + ``` + +### kvm:bridge 1.4 Connecting + +#### kvm:bridge 1.4.1 Connecting via login + +If you started the QEMU with a display, you can connect to it as root. +CAUTION for french users, it as QWERTY keyboard mapping, type`lqser` + +``` +USER "root" +PASS "laser" # i.e. "lqser" on AZERTY keyboards +``` +#### kvm:bridge 1.4.2 Connecting via SSH + +``` +# Wait until ssh/login is available in the VM +# Type password "laser" i.e. "lqser" on AZERTY keyboards +ssh root@${GUEST_IP} +``` + + + +# Todos +[] Export USB devices +[] Nginx redirect to https +[] Nginx wss websockets redirect + +[x] @todo deploy http(+s with snakeoil cert) with nginx +[x] @todo read IP from updateUI.pu OR BETTER read IP addresses from a common file diff --git a/build.json b/build.json index 1eb9d29..78aae05 100644 --- a/build.json +++ b/build.json @@ -95,7 +95,6 @@ "sleep 3", "apt update", "apt install -y --no-install-recommends cmake git libasound2-dev libjack-dev libsdl1.2-dev network-manager nginx portaudio19-dev python3-dev python3-pip python3-rtmidi redis-server screen ssh ssl-cert ", - "systemctl disable network-manager.service", "pip3 install setuptools", "pip3 install DMXEnttecPro mido numpy pysimpledmx redis scipy ", "git clone https://github.com/ptone/pyosc --depth 1 /tmp/pyosc && cd /tmp/pyosc && ./setup.py install ", diff --git a/files/root/.bashrc b/files/root/.bashrc deleted file mode 100644 index ab21de5..0000000 --- a/files/root/.bashrc +++ /dev/null @@ -1,79 +0,0 @@ -cd /opt/LJ -echo -e "\n\e[1;31m" -cat << HEREDOC - \ \ / | | | | - \ \ \ / _ \ | __| _ \ __ \__ \ _ \ __| _ \ | | - \ \ \ / __/ | ( ( | | | | __/ | ( | | \ | - \_/\_/ \___| _| \___| \___/ _| _| _| \___| \__| \___/ _____| \___/ -HEREDOC -echo -e "\e[0m\n" - -# Check the ip address on the machine -checkNetwork(){ -ping=$( ping 1.1.1.1 -c 1 -W 2 &>/dev/null; echo $?;) - - # Net is working, escape - [[ 0 -eq $ping ]] && return - - echo -e "\nOops... No network configured yet..." - - # Eventually, use nm-tui for a graphical (ncurses install) - read -e -p "Do you want to set up network via the ncurses tool? [yN]: " - [[ "${REPLY^^}" == "Y" ]] && { nmtui; return; } - - # Get the ethernet interface - # 772 is the loopback device, cf. http://lxr.linux.no/linux+v3.0/include/linux/if_arp.h#L67 - for f in /sys/class/net/* ; do - [[ 772 != $(cat "$f/type" ) ]] && interface=$(basename $f) - done - - [[ -z "$interface" ]] && { echo -e "\e[31mFatal Error : no network interface configured."; return; } - echo "Found network interface '$interface'" - - # Ensure the interface is up - ip l set $interface up - - ipList=$( ip address show | grep global ) - ipRoute=$( ip route show | grep default ) - - [[ -z "$ipList" ]] && { - echo -e "\nNo IP address configured. Please set one." - read -e -i '192.168.2.100/24' -p "Which address/range do you want to use (or 'x' to skip)? " ipAddr - [[ 'x' != "$ipAddr" ]] && { - ip address add $ipAddr dev $interface - } - } - [[ -z "$ipRoute" ]] && { - echo -e "\nNo IP route configured. Please set one." - read -e -i '192.168.2.1' -p "Which routing address do you want to use (or 'x' to skip)? " ipAddr - [[ 'x' != "$ipAddr" ]] && { - ip route add default via $ipAddr dev $interface - } - } - - -} -checkNetwork -[[ ! -f /tmp/.first_run ]] && { - touch /tmp/.first_run ; - echo -e "\e[1mCaution! configuring the server and lasers network is mandatory for the app to work." - echo -e "Type the "c" key immediately to start the configuration." - echo -e "\e[0m" - echo -e "Everytime you will login, the configure and documentation options will be offered to you." - echo -e "Or use the commands 'config' or 'usage' any time to access the same functions." - echo -e "\e[0m" -} -config(){ cd /opt/LJ ; /usr/bin/python3 configure.py; } -usage(){ cat /opt/LJ/README.md; } - -echo -e "\e[1m" -read -e -n 1 -p "Do you want to (c)onfigure the app, (r)ead documentation, or (n)othing: " -echo -e "\e[0m" -case $REPLY in - (c): - config - ;; - (r): - usage - ;; -esac