How to use the state partition?


I’m new to using BalenaOS and I’m currently trying use it to set up multiple services on my raspberry pi. In the description of the architecture overview it shows that the state partition can be used to modify the otherwise read-only system file tree. While I did find a file system mounted at /mnt/state/root-overlay, adding files to it did not result in any modifications to the /etc/ directory (confusingly, changing already existing files did change them in /etc/). I even tried rerunning the resin-state service, but it didn’t help either.

Currently I’m trying to use it to mount a swap file and an external hard drive in the fstab which seems like a pretty standard use case to me.

Any thoughts?


Hi there,

You can mount an external drive from within a service container by enabling udev ( )and then mounting it via an appropriate method (for block device, systemd is required as fstab within a container will not work), details of which can be found here: . The node can only be mounted in one service container, although other customers have developed systems to share this data (such as a shared NFS mount).

The state partition in balenaOS is used for specific systemd services and is bound at boot time. We don’t support files that aren’t used by the system (and the state partition is pretty small, unlike the permanent data partition).

For actually mounting devices via the host balenaOS itself, we don’t currently support this. I’m sorry that this is probably not the answer you’d like, but by mounting in-service and then sharing, you should be able to handle most usecases.

Best regards,


Thanks for the quick reply! My use case is a static drive (changing the fstab, would only happens during the initial setup), which should for all intents and purposes be treated as an internal drive. The swap file on it should be used system-wide so I guess doing stuff in the service container is not an option for me.

I will probably just end up modifying the ISO…

The traditional approach would be to edit fstab indeed. But generally speaking, there shouldn’t be a need to do anything on the hostOS in a containerised environment.

I’d recommend in your container start script, you mount your external hard-disk, make a swap file on the hard disk, and then mount it as swap.

This should be possible from a privileged container.


Thanks, @zubairlk for the tip.

I’m new to docker, so I might be missing something obvious.

When I run a privileged docker container, I still can’t mount the hard disk (it is not mounted when I’m in the root shell).

My sample docker compose is:

version: '2'
    build: ./mountHD
    restart: always
    privileged: true

The Docker file is:

FROM balenalib/raspberrypi3-alpine


COPY ./ .
CMD ["/bin/sh", ""]

while contains:


mkdir -p "$HD_MOUNTPOINT" && mount /dev/sda1 "$HD_MOUNTPOINT"

while true ; do sleep 1000 ; done

To my understanding, this is more or less what is done in the “Mounting external storage media” section of the guide.

So I guess I’m not quite sure if I’m doing something wrong in the Dockerfile or if a privilged container cannot affect the state of the system and @zubairlk was referring to a different way of achieving this goal.

You cannot mount stuff to the host – Zubair’s suggestion is about mounting the volume inside your container, which as far as I can see, the script you came up with would do this just fine, so when you SSH into your container it should be visible.

Ok, that makes sense, but I’m still a bit confused.

Assuming I have a container A which runs with privileges. It can connect to peripherals, so it mounts the hard drive and configures a swap file. Then I have a non-privileged container B which runs a service. Can B mount a part of the file system from the hard drive via docker bind mounts? When whatever happens in B runs out of memory, does the OS use the swap file that was set up in container A?

From what I understand the answers are both no. This means that in order to be able to use swap, I need all the containers to be privileged and they all have to mount their own dedicated swap file.

This is suboptimal for me for the following reasons:

  1. All the containers need to know about the underlying system (hard disk + the fact that the system does not have enough RAM) and are privileged.
  2. The containers need to know about each other (in order to not overwrite each other’s swap).
  3. The size of all the swap files sum up

The main reason I want to switch to a containerized setup is to avoid problems 1+2.

The Raspberry Pi is a great device, but running web services (e.g. GitLab) without swap space and only 1 GB of RAM is impossible. Having the swap on the SD card is not great for reliability and large capacity SD cards are a lot more expensive than hard disks.

Hi @alehed
generally you are right with what you say. If you need swap it would best be enabled on the host OS but currently balena does not allow you to configure that as far as I am aware…
If memory is the main bottleneck using a raspberrypi 4 instead might be an option. Balena can now run in 64 bit mode on that device and it supports up to 4GB of ram. It also has a faster network interface and faster USB. My experience with attaching an external harddisk to a raspberry pi 3 (via USB) have been rather disappointing regarding speed. You would not want to use that as SWAP.

Thanks for the quick reply!

I am considering getting one of those and 4 GB is definitely better, but currently GitLab says 8 GB is recommended so I would still want some swap around just in case (especially since I might want to run more than just GitLab).

For now I’m going to simply adjust the iso for my needs and see how it runs on the Raspberry Pi 3 (I did run GitLab under Raspbian before and it worked, despite being slow).

Good luck. Sorry I have no better solution for you. Playing with container-internal swap is probably your best bet, but I am not quite sure how that will work as I was assuming the memory management (and swap) would be handled by the kernel rather than by containers.