.. _shared-resources: Using devlib on shared resources ================================ This section describes how to use devlib safely on a shared Linux host. It is primarily concerned with host-side files that may contain sensitive connection data, along with host-side output written by devlib such as pulled files, traces, and other collected artifacts. devlib operates within the permissions of the calling user. It does not secure the host filesystem for you. Users therefore remain responsible for protecting SSH keys, any config-like files that contain credentials, and any host-side paths chosen for output or copied data. Platform assumptions -------------------- The examples in this section assume a Linux host with standard Unix file permissions. The examples use tools such as ``chmod``, ``ls``, ``find``, and ``df``. Protecting connection data -------------------------- ``connection_settings`` may contain sensitive values such as usernames, passwords, hostnames, SSH private key paths, and adb device identifiers. If you store any of that data in local files, those files should be readable and writable only by the owning user. For example, an SSH private key or local YAML file containing connection data should be protected like this: .. code-block:: bash chmod 600 ~/.ssh/id_rsa chmod 600 ~/devlib-device.yaml ls -l ~/.ssh/id_rsa ~/devlib-device.yaml After running ``ls -l``, the left-most permissions field should start with ``-rw-------``. That means only the owning user can read or write the file. .. important:: On shared systems, users are responsible for protecting any local files that contain sensitive connection data. Do not assume devlib will manage those file permissions for you. Secure file placement --------------------- Sensitive files should be stored in directories that are only user readable. That applies to SSH keys, local config-like files, scripts or any temporary files that embed credentials. Typical checks: .. code-block:: bash ls -ld ~/my_private_folder For a private directory, the permissions should usually be ``drwx------``. Avoid storing sensitive files in shared project directories unless access is restricted appropriately. Avoid committing such files to version control and do not paste them into logs. Handling host-side output safely -------------------------------- devlib can write substantial data to the host filesystem. Common examples include: - files retrieved with :meth:`Target.pull() ` - screenshots captured with :meth:`Target.capture_screen() ` - collector output such as traces or logs - generated SDK, buildroot, or Docker artifacts from helper tooling under ``tools/`` Some of these writes go to paths you choose explicitly, while others go to repository-local or tool-managed locations. In practice, that means users need to think about both confidentiality and capacity before starting long-running or storage-heavy workflows. Choose output locations deliberately, especially on shared systems. Prefer directories owned by the calling user and avoid writing sensitive output into locations which are readable to others. Make sure to provide a suitable output location. For example: .. code-block:: bash mkdir -p ~/ chmod 700 ~/ ls -ld ~/ You can then use paths under that directory for pulled files, screenshots and collector output. Where devlib writes on the host ------------------------------- The host-side write pattern depends on the feature being used: - :meth:`Target.pull() ` writes to the destination path provided by the caller - collectors write to the ``output_path`` supplied by :meth:`CollectorBase.set_output() ` - screenshots and similar helper methods write to the path given by the caller - ``tools/android/setup_host.sh`` creates a persistent ``tools/android/android-sdk-linux`` tree - ``tools/buildroot/generate-kernel-initrd.sh`` creates a persistent buildroot directory under ``tools/buildroot/`` - Docker-based workflows can create large image layers, caches and test artifacts on the host .. note:: devlib does not apply host-side quotas or automatic retention policies for these paths. Users are responsible for choosing appropriate destinations and cleaning them up when they are no longer needed. Checking for overly broad permissions ------------------------------------- If you have copied files around manually, or aren't sure whether an output tree is too broadly accessible, inspect it like shown below: .. code-block:: bash find ~/ -perm /077 -ls If this command produces no output, then no group or other permission bits are set anywhere under ``~/``. Managing disk usage ------------------- Some devlib workflows can consume significant host storage, particularly traces, collector output, Android SDK setup, buildroot builds and Docker artifacts. Before running storage-heavy workflows on shared or small filesystems, check capacity first: .. code-block:: bash df -h . du -sh ~/ du -sh tools/android/android-sdk-linux tools/buildroot 2>/dev/null Some Linux filesystems keep a small amount of reserved space, so writes may start failing before the filesystem is literally 100% full. This can help preserve limited system recoverability, but it must not be relied upon as protection against host-side disk exhaustion. Users should still monitor free space and clean up devlib-generated artifacts proactively. Cleaning up safely ------------------ Remove old output and build artifacts when they are no longer needed, but be explicit about what is being deleted. On shared systems, avoid broad cleanup patterns in locations that may contain other users' data. Checklist before large runs --------------------------- Before starting a storage-heavy devlib workflow: - verify that the chosen output directory is owned by you and is not broadly accessible - confirm there is enough free space on the filesystem that will receive the output - decide whether the workflow writes to a caller-chosen path, a repository-local path or both - check whether old traces, screenshots, build artifacts or SDK files could be removed first - avoid running long captures on small or shared filesystems without monitoring growth Summary ------- When using devlib on shared resources, the main points to remember are: - protect SSH keys and any local files containing connection data with owner-only permissions - keep sensitive files out of world-readable directories - choose host-side output paths deliberately and restrict them to the owning user where possible - check permissions explicitly after copying or reorganizing output - monitor disk usage for traces, pulled files, SDK artifacts, and build outputs