weakbox

Create a weak container for running programs from a different Linux distribution
Log | Files | Refs | LICENSE

readme.md (2880B)

      1 # weakbox
      2 
      3 **weakbox** is a tool for Linux designed to create a weak (not secured) container for running programs from another Linux distribution. It is particularly useful for executing glibc-based programs (mostly closed-source software) under systems that are musl-based.
      4 
      5 ## Features
      6 
      7 - Create a container environment for running programs from different Linux distributions.
      8 - Bind mount directories from the host system into the container.
      9 - Map user and group IDs inside the container.
     10 - Customizable root path for the container.
     11 - Option to run commands within the container as `root`.
     12 
     13 ## Installation
     14 
     15 To install **weakbox**, simply clone the repository and compile the source code:
     16 
     17 ```bash
     18 git clone https://github.com/friedelschoen/weakbox.git
     19 cd weakbox
     20 make
     21 sudo make install # which installs /usr/bin/weakbox and /usr/share/man/man1/weakbox.1
     22 sudo make PREFIX=... install # which installs $PREFIX/bin/weakbox and $PREFIX/share/man/man1/weakbox.1
     23 ```
     24 
     25 ## Usage
     26 
     27 Run **weakbox** with the desired options and command to execute within the container:
     28 
     29 ```bash
     30 weakbox [options] command ...
     31 ```
     32 
     33 By default `command` is executed, if command is omitted current shell or `/bin/bash` is executed.
     34 
     35 ### Options
     36 
     37 - `-h`: Display usage information.
     38 - `-s`: Run the specified command within the container as root.
     39 - `-v`: Enable verbose mode for debugging purposes.
     40 - `-r path`: Set the root path of the container to `path`. By default the container lays at `$WEAKBOX`.
     41 - `-b source[:target]`: Bind mount the specified source directory to the target directory within the container. Target is relative to `root`.
     42 - `-B source`: Remove a default bind mount from the container.
     43 - `-u uid[:uid]`: Map user IDs inside the container.
     44 - `-g gid[:gid]`: Map group IDs inside the container.
     45 
     46 ### Default Mounts
     47 - `/dev`: directory containing all devices
     48 - `/home`: home directories of users
     49 - `/proc`: directories containing information about processes
     50 - `/sys`: system directories for various devices
     51 - `/tmp`: temporary directory
     52 - `/run`: temporary directory for daemons and long-running programs
     53 - `/etc/resolv.conf`: nameserver-resolution configuration
     54 - `/etc/passwd`: file containing information about users
     55 - `/etc/group`: file containing information about groups
     56 
     57 ### Examples
     58 
     59 1. Run a program within the container:
     60 
     61 ```bash
     62 weakbox -s /path/to/program
     63 ```
     64 
     65 2. Create a container with custom root path and bind mount directories:
     66 
     67 ```bash
     68 weakbox -r /custom/root -b /host/dir:/dir /path/to/program
     69 ```
     70 
     71 3. Map user and group IDs inside the container:
     72 
     73 ```bash
     74 weakbox -u 1000:1000 -g 1000:1000 /path/to/program
     75 ```
     76 
     77 ## Contributing
     78 
     79 Contributions are welcome! Feel free to submit bug reports, feature requests, or pull requests through GitHub issues and pull requests.
     80 
     81 ## License
     82 
     83 This project is licensed under the zlib-license. See the [LICENSE](LICENSE) file for details.