[HOWTO] Find your way around in the Porteus File Structure

Getting Started in Porteus: finding your way around

To view the discussion about this document, or to ask a question about it, visit this thread on our forum

Ok, so now that you have Porteus installed and running, where do you go from here? How do you configure your system (and make your changes stick after rebooting), where does everything go, and where do you add or remove modules? Why?

What makes Porteus different from most linux distributions is it's modular design and the use of aufs (Another Union File System) to turn modules into a live operating system. This takes place through the Linux Live Scripts, which have been modified by the Porteus maintainers to produce an ultra-fast, sleek, and robust operating system.

Find out more about modules and what they are here.

In a nutshell, All of the files that make up the system are stored in modules, which are folders that have been archived (using SquashFS and the new LZMA2 compression algorithm). When the system boots up, all of the modules are mounted into the live filesystem. Configuration scripts set up your specific hardware and configure your display, and your desktop environment (KDE, MATE, Xfce, etc) starts up.

So, what we have in Porteus are two categories of files: The files that are active and visible in your live filesystem while you are running Porteus, and the files that sit on your CD, USB drive, or hard drive, which are used to build the live filesystem as it boots up. This can make it confusing for new users, because any files that are saved to a particular location in the live filesystem (e.g. /home/guest/Downloads/myfile.txt) are not saved to that same exact location on your storage media. Having a better understanding of how the various files come together to build your live filesystem will greatly increase your ability to use, configure and enjoy Porteus.

The Porteus ISO contains two directories: /boot and /porteus. The /boot folder contains your bootloader configuration files, installation scripts, a few utilities, documentation, and the linux kernel (vmlinuz) and initrd. When you first start your computer, the bootloader starts the kernel and the kernel starts the initrd. With the initrd loaded, the system is now capable of mounting xzm modules, which make up all of the other files in the standard Porteus system.

Inside the /porteus directory you will find all of the files (other than the kernel and initrd) that are used to build the live filesystem. When Porteus is first installed, the modules in /porteus/base are the only ones that get mounted into the live system. Modules are inserted in alphanumerical order, so module 000-kernel.xzm is added first, then 001-core.xzm, etc.

Also inside the /porteus folder are some empty directories, which can be used for customizing your system:

/porteus/modules will hold .xzm modules that you want added to your system every time you boot up. Any modules in this directory will be injected to your filesystem immediately after the system is done adding the modules from /porteus/base.

/porteus/optional will hold .xzm modules that you don't want added during startup. You can activate these modules while the system is running, and use them as needed. Modules can be activated by double clicking on them, or by entering 'activate /path/to/module/module.xzm' from the command line. These modules can also be activated during startup by using the "load=" cheatcode (e.g. load=/porteus/optional/chrome.xzm).

If you choose to save your changes persistently (the default boot option), your changes will be saved in yet another location: /porteus/changes (if your storage media is formatted with a linux filesystem) or /porteus/save.dat (used primarily with storage media formatted with a windows filesystems). Any files that you add, modify, or delete are saved here in a "fake root" directory, and these changes are applied to your live filesystem at startup. Changes are loaded into the system after all of the modules in /porteus/base and /porteus/modules are activated.

Find out more about save.dat containers here.

The /porteus/rootcopy/ directory is a special directory where you can place individual files that you want added to your live system, without needing to convert them to modules. These files are added to the live system after all of the modules and your saved changes, and will overwrite any files with the same path and name that are already there. Find out more about how to use this feature here.

The last files that are added to Porteus as it starts up are magic folders. Magic folders are not present in your system by default, but you can set them up using the "magic-folders" setup tool in Porteus Settings Centre, or from the command line with the 'magic_folders' command. These folders allow you save changes from a particular folder in your live filesystem to another folder on your storage media. More on magic folders can be found here.

Many of the files that have been pulled from the above sources can be viewed from within the live filesystem. Navigating through these folders can help you see the building blocks of your system. They are visible inside the /mnt/live/memory directory:

/mnt/live/memory/images contains a directory for each module that has been activated in the system, and you can view all of the files (as read only) that are contained within that module.

/mnt/live/memory/changes contains all of the files that have been modified in your system. These are the files that are copied to your save.dat or the /porteus/changes directory on your storage media.

With so many different locations for the files that are used to build the live system, it's easy to get confused at first. But as you continue using and experimenting with Porteus, you will come to understand the beauty of this system and its flexibility. Programs can be added and removed as quickly and easily as moving a file into the right folder; you can switch between saving your changes and booting into a completely fresh installation in a heartbeat; you can install both editions of Porteus on the same partition and share data between them right from a magic folder on your desktop, and you can do it all on a device that weighs ten grams and fits in your pocket, and you can run it on just about any PC you come across.