diff --git a/board/common/README.txt b/board/common/README.txt new file mode 100644 index 00000000..87a5a576 --- /dev/null +++ b/board/common/README.txt @@ -0,0 +1,130 @@ +Welcome to Infix! +================= + +Nice to meet ❤️ you! If you are reading this then you have possibly +just downloaded and unpacked a release build and are curious about how +to proceed from here. + +To test Infix You need a Linux 🐧 system with Qemu or GNS3 installed. +We recommend Debian based systems, like Ubuntu and Linux Mint. + +> For a pain-free experience we recommend enabling CPU virtualization in +> your BIOS/UEFI, which for many computers is disabled by default. + +From this point we assume you have your x86_64/AMD64 based Linux system +up and running. Time to start your favorite terminal application! 😃 + + +Installing Qemu +--------------- + +This README focus on getting you started with Qemu. From a terminal, +install (at least) the x86/x86_64 emulator. The 'virt-manager' is a +package that helps pull in other dependencies you may need: + + $ sudo apt install qemu-system-x86 virt-manager + +That's it. + + +Running Infix in Qemu +--------------------- + +Depending on how your Linux installation is set up, the following may +require being run with superuser privileges, i.e., you may need to +repend the command with 'sudo'. + + $ ./qemu.sh + +You should now see the Infix init system booting up. When the final +"Please press Enter to activate this console." is shown, press Enter +and the login: prompt is displayed. + +The default credentials for the demo builds is + + login: admin + password: admin + + Infix -- a Network Operating System v24.09.0-rc1 (hvc0) + infix-00-00-00 login: admin + Password: + .-------. + | . . | Infix -- a Network Operating System + |-. v .-| https://kernelkit.org + '-'---'-' + + Run the command 'cli' for interactive OAM + + admin@infix-00-00-00:~$ + +You're in! Play around in your sandbox as much as you like, if you +run into problems or have questions, please see the documentation, +and don't hesitate to get in touch with us! 😃 + + - https://github.com/kernelkit/infix/tree/main/doc + + +Customizing your "Hardware" +--------------------------- + +For more Ethernet ports in your emulated system you need to change the +Qemu configuration used for Infix. This can be done using a menuconfig +interface, which requires the following extra package: + + $ sudo apt install kconfig-frontends + +We can now enter the configuration: + + $ ./qemu.sh -c + +Go down to *Networking*, select *TAP*, now you can change the *Number of +TAPs*, e.g. to 10. Exit and save the configuration, then you can start +Qemu again: + + ./qemu.sh + +> Make sure to do a factory reset from the CLI, otherwise you will be +> stuck with that single interface from before. + + +Errors on Console +----------------- + +If you see the following line printed one or more times, don't panic. + + LABEL=var: Can't lookup blockdev + +See the Customizing section above. To silence the error you need to +create another writable partition for Infix to store logs, container +images, etc. Look for the 'var' keyword, you can adjust the size of +the partition. + + +Graphical Network Simulator 3 (GNS3) +------------------------------------ + +GNS3 is a very powerful front-end to Qemu which takes care of creating +virtual links between network devices running in Qemu. This README is +only link to the material you need. This directory holds the appliance +file, .gns3a, that references image files also in this directory, that +you need to load into GNS3. + +The necessary extra packages are available through the offical PPA. If +you don't know what a PPA is, read up on that first: + + - https://launchpad.net/~gns3/+archive/ubuntu/ppa + +There's a lot of tutorials and guides online, start here: + + - https://docs.gns3.com/docs/ + + +About +----- + +Infix is a free, Linux based, immutable Network Operating System (NOS) +built on Buildroot, and sysrepo. A powerful mix that ease porting to +different platforms, simplify long-term maintenance, and provide easy +management using NETCONF, RESTCONF, or the built-in command line +interface (CLI) from a console or SSH login. + diff --git a/board/common/post-image.sh b/board/common/post-image.sh index ccd8e70e..cebc9f9e 100755 --- a/board/common/post-image.sh +++ b/board/common/post-image.sh @@ -102,3 +102,6 @@ rm -f "$BINARIES_DIR/qemu.cfg" CONFIG_="CONFIG_" BR2_CONFIG="$BINARIES_DIR/qemu.cfg" \ "$O/build/buildroot-config/conf" --olddefconfig "$BINARIES_DIR/Config.in" rm -f "$BINARIES_DIR/qemu.cfg.old" "$BINARIES_DIR/.config.old" + +# Quick intro for beginners, with links to more information +cp "$BR2_EXTERNAL_INFIX_PATH/board/common/README.txt" "$BINARIES_DIR/"