[fix] more doc + fixes

This commit is contained in:
alban 2020-09-24 14:34:44 +02:00
parent 9fd6ecfcdb
commit fbf86f5aa8
3 changed files with 233 additions and 80 deletions

233
README.md Normal file
View File

@ -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 <Edit a connection><Add a connection> and to forget to <Activate> 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

View File

@ -95,7 +95,6 @@
"sleep 3", "sleep 3",
"apt update", "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 ", "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 setuptools",
"pip3 install DMXEnttecPro mido numpy pysimpledmx redis scipy ", "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 ", "git clone https://github.com/ptone/pyosc --depth 1 /tmp/pyosc && cd /tmp/pyosc && ./setup.py install ",

View File

@ -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