NOTE: Documentation was previously neglected and is just now being created. There are hundreds of terminal commands for example that are not written anywhere but in the OS and several tools and enhancements that are present but have zero reference. There is much work to be done.
Frequent updates to this document can be expected.
Installation
2 methods of installation; ISO install and bootstrap script.
ISO – Standard install procedure. ISO boots into a live environment with an icon on the desktop to begin the install. After the process completes you will be prompted to reboot. On first boot the initial config program is initiated, with progress bar visible, and will perform setup tasks that are only possible on a completed installation. When the configurations are complete the Welcome Dashboard is presented. Further details will be covered in the First Steps section.
Bootstrap – Same as above, only initiated in a fresh Ubuntu cloud instance with downloaded script, thus no live preview.
First steps
On the first login after an install, the initial setup program will be activated. If a network connection isnt detected you will be prompted to connect before moving forward, This will ensure everything on the system is current and perform any updates/upgrades available. Also any configurations needed will be carried out such as plugins and specific settings that can only be performed on a target system and cannot be preloaded in the install media. Finally, a cleanup will occur. Depending on whether there were large packages to upgrade released after the ISO used was built, the clean-up will likely be the longest of the steps as it removes all the packages needed for the Live ISO and install the Ubiquity doesn’t automatically remove. When the setup is complete you will be greeted by the Welcome Screen.
Welcome Screen- Consists of 9 options:
(Order may not be reflected as it appears here)
- Make Swap- This tool creates a swap file of a chosen size and adds entry to fstab to make the swap persistent between reboots. You can choose any size desired up to 8 GB. While initially included to allow swap space availability on cloud installations, you may use this tool on any installation in lieu of, or in addition to a swap partition.
- Shark Extras- Short cut to installers and other goodies. These are also available in the main menu and in your home folder.
- Sudo Policy – Gives the option of changing from SharkLinux default to traditional sudo behaviour.
- System Settings – General system wide settings.
- System Backups – Perform a backup of the fresh installation to easily rollback changes.
- System Maintenance – Toggle automatic system upgrades and cleanups
- System timezone- Sets the system time to a desired timezone. Mainly used in cloud environments where choosing a location/time zone isnt an option during the installation.
- Bug Reports – Questions? Found a bug? Want to email us a death threat? This is the place to do so (hopefully not the 3rd option)
- SharkLinux Expansion- This one was saved for last on purpose. It is HIGHLY recommended this be one of the very first things you do. The install sets up the base system and gets you started but at this point your really only have a xenial install with MATE desktop and a handful of standard desktop programs. For some this is sufficient but in order to make use of all of SharkLinux’s features and really experience the OS as intended you’ll inevitably need to install the expansion. It’s best just to do this immediately. Absolutely no upstream packages are enabled without the expansion and many one-click installs depend on its installation.
Close- Not really an option but it’s a button. SPOILER ALERT – it closes the window. It also kicks off the wallpaper changing utility so you’re not stuck looking at the stock SharkLinux branded background that persists in the LIVE system and up to this point in the full install. It could take up to 5 mins for the first change to occur but will likely happen quicker than that.
Featured Software
Cockpit
A remote manager for GNU/Linux servers
Cockpit is a server manager that makes it easy to administer your GNU/Linux servers via a web browser. Cockpit started as Red Hat project and supports management of systemd as well as other services. Access is via https://localhost:9090 but you can add other instances of servers where cockpit is installed in the cloud and manage them as well.
Cockpit makes it easy for any sysadmin to perform simple tasks, such as administering storage, inspecting journals and starting and stopping services.
Jumping between the terminal and the web tool is no problem. A service started via Cockpit can be stopped via the terminal. Likewise, if an error occurs in the terminal, it can be seen in the Cockpit journal interface.
Cockpit was featured in the June 2017 issue of Linux Pro Magazine. Current information can be found at http://cockpit-project.org/running.html, http://cockpit-project.org (home page) and https://github.com/cockpit-project/cockpit
Other Docs: http://www.projectatomic.io/docs/
Ubuntu Cloud:
Ubuntu Cloud is supported via a local instance of qemu/kvm. On first run, SharkLinux creates the local Ubuntu Cloud Instance for you. To install a virtual machine from the Ubuntu Cloud, you run “Ubuntu Cloud” from the Virtual-Machines group on SharkLinux where you will prompted for a machine name, username and password. Then you will be offered a choice of 5 Ubuntu releases from Precise 12.04 through Zesty 17.04. It will grab/sync the daily cloud image from the Ubuntu Cloud. More information on use of the Ubuntu Cloud can be found at https://www.ubuntu.com/cloud. Once “built” locally in qemu/kvm, you can access the virtual machine via the virt-manager (gui) and login using the provided username and password. Depending on your cloud provider it is possible to migrate these images to an openstack instance.
Vagrant:
Vagrant provisioning of virtual machines in the qemu/kvm environment is provided on SharkLinux. In Virtual-Machines, there are two instances name “SharkLinux” and “Xenial64”, both of which use vagrant to provision the respective virtual machines. Additional vagrant support is provided by a Vagrant Box converter to the qemu/kvm environment as well as the raw vagrant tools for provisioning. Unlike a standard install which favours VirtualBox, libvirt is the default provider for the machines provisioned using vagrant. Vagrant documentation starts here https://www.vagrantup.com/intro/getting-started/ and the HashiCorp hosts many of the cloud images used by SharkLinux
One example is the SharkLinux virtual machine that is installed via vagrant.
==> default: Adding box ‘SharkLinux/SharkLinux’ (v3.2) for provider: libvirt
default: Downloading: https://vagrantcloud.com/SharkLinux/boxes/SharkLinux/versions/3.2/providers/libvirt.box
Once installed, the vm is created in qemu/kvm you are automatically logged in via a terminal session using SSH keybased authentication. Exiting out automatically shuts down the domain in qemu/kvm.
vm’s can be starged via the vagrant up which will open the SSH connection as well using virsh and the graphical virt-manager.
SharkCloud:
SharkCloud is a cloud environment provided by SharkLinux and a graphical “SharkCloud” tool is provided for creating virtual machines from the SharkCloud environment, similar to the Ubuntu Cloud but with more choices of both Ubuntu and Debian environments. The tool uses officially released cloud images as found on aws or other major provider. The virtual machines can be started using the SharkCloud menu or via libvirt which includes virt-viewer, virsh, or the graphical virt-manager and accessed using the username/password created during the install. Using the SharkCloud, you can create a “temporary” instance in the SharkCloud, this machine is a 1 time use for quick testing and is deleted when it is shutdown/closed.
Stack Technologies:
LxDevstack and Kubernates are also support on SharkLinux. Networking backends are provided for these technologies as part of the default installation. Access to the implementation scripts is found in the virtual-machines group.
LXDock/QLC:
For LXDock please refer to official docs for upto date information.
qlc (quick linux container)
wrapper program with LXD/LXDock
Install:
LXD – installed by default
LXDock – autobuild script in software section
– or – use command ‘qlc-init’
How to use:
qlc <name> <arg>
-start creates new env
start may be replaced by a path to a shell script for provisioning
Other commands:
-start/up start a container
-stop/halt stop a container
-shell/bash Access the shell
-destroy/delete bye bye container
Other notes:
All containers launched with QLC:
Have a user account mirroring the username of the creator.
Have a shared folder to allow easy “passing of files” to/from host.
Firejail :
Firejail is a SUID program that reduces the risk of security breaches by restricting the running environment of untrusted applications using Linux namespaces and seccomp-bpf. It allows a process and all its descendants to have their own private view of the globally shared kernel resources, such as the network stack, process table, mount table.
Written in C with virtually no dependencies, the software runs on any Linux computer with a 3.x kernel version or newer. The sandbox is lightweight, the overhead is low. There are no complicated configuration files to edit, no socket connections open, no daemons running in the background. All security features are implemented directly in Linux kernel and available on any Linux computer.
Official Docs: https://firejail.wordpress.com
LinuxBrew:
Linuxbrew is a fork of Homebrew, the macOS package manager, for Linux.
It can be installed in your home directory and does not require root access.
Can install software to a home directory and so does not require sudo
Install software not packaged by the native distribution
Install up-to-date versions of software when the native distribution is old
Use the same package manager to manage both your Mac and Linux machines
For usage instructions refer to official docs
Docs: http://linuxbrew.sh
Netdata:
netdata is scalable, distributed real-time performance and health monitoring:
Everything netdata does is per-second so that the dashboards presented are just a second behind reality, much like the console tools do. Of course, when netdata is installed oubuntu cloudn weak IoT devices, this frequency can be lowered, to control the CPU utilization of the device.
netdata is adaptive. It adapts its internal structures to the system it runs, so that the repeating task of data collection is performed utilizing the minimum of CPU resources.
The web dashboards are also real-time and interactive. netdata achieves this, by splitting the work load, between the server and the dashboard client (i.e. your web browser). Each server is collecting the metrics and maintaining a very fast round-robin database in memory, while providing basic data manipulation tasks (like data reduction functions), while each web client accessing these metrics is taking care of everything for data visualization. The result is:
minimum CPU resources on the servers
fully interactive real-time web dashboards, withubuntu cloud some CPU pressure on the web browser while the dashboard is shown.
Docs: https://github.com/firehol/netdata/wiki
Cloud VM Management tools
Guacamole:
Guacamaole – Shark Specific Details ; The server is accessible at 127.0.0.1:8080. The default User/Passcode = admin/password. For general documentation and usage refer to official docs https://guacamole.incubator.apache.org/doc/gug/
Kimchi:
Kimchi is an HTML5 based management tool for KVM. It is designed to make it as easy as possible to get started with KVM and create your first guest.
Kimchi manages KVM guests through libvirt. The management interface is accessed over the web using a browser that supports HTML5.
Official Docs: https://github.com/kimchi-project/kimchi/tree/master/docs
FAQ
What’s the deal with the expansion and all the stuff that builds from source? If it’s so highly recommended why not just include it with the install?
For a number of reasons. Programs built from scripts are always pulled directly from the source. This ensures that any updates made by the creators are always present and that the most recent version is built. The build scripts also take care of any local configurations required to ensure the software being installed plays nicely with the rest of the system. Finally, its a matter of choice, convenience and maintain a reasonable size base. Not all programs are going to be used by everyone. While you may love using WINE, the next guy may not have use for it. Some of these programs can eat up decent amount of disk space so it’s best left to the end user if they want it. This works the same for the expansion- the base install already makes for an ISO that ranges from 1.4 – 1.7 gigabytes in size. To start packing all of these tools and software into the main base it wouldnt take long for an ISO so bloated in size it would discourage people from giving the OS a try.
Software X is available in the Ubuntu repo’s. Why host it in the SharkLinux repo?
Ubuntu has a great selection of software, however some programs are not updated to newer versions despite being compatible with a xenial filesystem. For this reason some packages are made available through our repo to ensure new versions are pushed to the OS as they become available.
Software X released a new version this week, why is it not available on the system yet?
Not ALL programs are kept on the upstream release plan. Either there was deemed little benefit to going to versions not available by default in the Ubuntu repo or newer versions are simply not compatible with xenial or other software in the OS. If the package in question IS one that we keep current then;
Most likely that the package is still being tested to ensure no major bugs arise from the upgrade. New versions arent just blindly added to the public repo but are tested first privately and then in Edge to make sure all is well. A new version is usually pushed to the standard system in 2-3 days after release. The other cause may be that there was, in fact, issues that were found in the new version and the update is on hiatus until a bux fix is available. A recent example would be Vagrant. The 1.9.0 release was found to have a bug present which affected compatibility with plugins that are present in SharkLinux. For that reason the upgrade was held back and we stuck with the 1.8.9 package while we watched for a solution. Inevitably, the 1.9.1 release addressed these issues and 1.8.9 was then upgraded directly to 1.9.1. Lastly, It IS possible we may just have missed the new version and would benefit from a gentle reminder. Don’t hesitate to touch base.
Why isn’t Software X used instead of Software Y?
This one is tough. Choices had to be made and inevitably the programs included were the one’s chosen. Its not something easily answered with a catch-all response as the reasons vary based on the program. Reasons range from ease-of-use, user ratings, level of support and development. Another reason possible is the hard requirement that every program included by default or available in the shark-repo MUST, again for effect MUST function in a (KVM) cloud environment. Program X could be the best of it’s kind by a long shot, if it doesnt work in the cloud it will not be included. Period.
How do you know if “X” works in the cloud?
That’s easy. SharkLinux is developed and tested exclusively in the cloud. In fact in the beginning more bugs were found on bare-metal installs as they pertained to things that would be non-factors in a cloud setup and thus were embarrassingly overlooked. The first time SharkLinux was tested on bare-metal, that is outside of a virtual machine or cloud instance but on a physical PC it was noted there was zero wifi support present. Hard to believe this was missed but wifi had never been a factor in the cloud or in VMs where the network is fed into the environment from the host.