runon/README.md

261 lines
6.4 KiB
Markdown
Raw Normal View History

2021-04-29 17:58:45 +02:00
RUNON - Run your commands in any systems
========================================
2021-04-30 20:32:20 +02:00
(c) 2021 Gilles Grandou <gilles@grandou.net>
licensed under GPL-2.0.
2021-04-29 17:58:45 +02:00
home: https://git.grandou.net/gilles/runon
Quick HOWTO
-----------
$ grep ^PRETTY_NAME /etc/os-release
PRETTY_NAME="Debian GNU/Linux 10 (buster)"
$ runon centos7 grep ^PRETTY_NAME /etc/os-release
PRETTY_NAME="CentOS Linux 7 (Core)"
$ runon ubuntu20.04 grep ^PRETTY_NAME /etc/os-release
PRETTY_NAME="Ubuntu 20.04.2 LTS"
$ runon debian9 grep ^PRETTY_NAME /etc/os-release
PRETTY_NAME="Debian GNU/Linux 9 (stretch)"
2021-04-30 20:35:17 +02:00
$ runon centos7 xclock
2021-04-29 17:58:45 +02:00
[xclock launched!]
Install
-------
Installation is only tested on Debian 10, even though it should work
straightforward on any equivalent system.
2021-04-30 20:21:55 +02:00
### Docker Install
2021-04-29 17:58:45 +02:00
sudo apt install docker
Check that your user is part of `docker` group:
sudo adduser <user> docker
2021-04-30 20:03:24 +02:00
If needed, you need to logout and login again for the new group to
become active.
2021-04-29 17:58:45 +02:00
2021-04-30 20:21:55 +02:00
### manual install
2021-04-29 17:58:45 +02:00
cd <tools>
git clone https://git.grandou.net/gilles/runon
2021-04-30 20:03:24 +02:00
local install, in your `~/local/bin` (or wherever directory which is in your
2021-04-29 17:58:45 +02:00
PATH):
2021-04-30 20:03:24 +02:00
cd <runon>
./install local
2021-04-29 17:58:45 +02:00
2021-04-30 20:03:24 +02:00
or
2021-04-29 17:58:45 +02:00
2021-04-30 20:03:24 +02:00
./install local <your_bin_path>
2021-04-29 17:58:45 +02:00
2021-04-30 20:03:24 +02:00
system install, for all users:
2021-04-29 17:58:45 +02:00
2021-04-30 20:03:24 +02:00
cd <runon>
sudo ./install system
2021-04-29 17:58:45 +02:00
2021-04-30 20:03:24 +02:00
each user can have its own configuration in `~/.config/runon/runon.conf`
if needed.
2021-04-30 20:21:55 +02:00
### uninstall
2021-04-30 20:03:24 +02:00
simply pass `-u` to install command you have used, eg.:
./install local -u
./install local -u <dir>
sudo ./install system -u
2021-04-29 17:58:45 +02:00
2021-04-30 20:21:55 +02:00
### some convenient links
2021-04-30 11:38:11 +02:00
you can create soft links to `runos` to simplify calls:
cd /usr/local/bin
ln -s runon centos7
now calling `centos7 ...` is equivalent to call `runos centos7 ...`:
centos7 xclock
2021-04-29 17:58:45 +02:00
Usage
-----
With the default configuration, a seamless environment is set up,
allowing to transparently run commands in various environments, while
keeping:
* user environment (uid, gid, password, home directory, ...)
* X support to run graphical applications
2021-04-30 20:21:55 +02:00
### Basic usage
2021-04-29 17:58:45 +02:00
runon [options] <osname> <command>
runon -h
2021-04-30 20:21:55 +02:00
### available options
2021-04-29 17:58:45 +02:00
* `-v` verbose output, this is really usefull when running new
containers for the first time, as the initial docker build can be
2021-04-30 20:35:17 +02:00
quite long (several minutes) especially with slow internet link.
If the command seems to be stalled, don't hesitate to interrupt it
(with `CTRL-C`) and to restart it with `-v`.
2021-04-29 17:58:45 +02:00
* `-u` forces the container image to be updated, useful if the
distribution has been updated and you want to use it. Otherwise,
2021-04-30 20:35:17 +02:00
if a container has been already built, it will be used directly
without doing any network access.
2021-04-29 17:58:45 +02:00
* `-c <configfile>` uses a custom config file, useful to try new
distribution without breaking your running config.
2021-04-30 20:21:55 +02:00
### Interactive shell
2021-04-29 17:58:45 +02:00
Just run:
runon <osname>
while start an insteractive shell in the container system:
gilles@host:~$ runon centos8
(centos8) gilles@host:~$ cat /etc/os-release
NAME="CentOS Linux"
VERSION="8"
ID="centos"
ID_LIKE="rhel fedora"
VERSION_ID="8"
PLATFORM_ID="platform:el8"
PRETTY_NAME="CentOS Linux 8"
ANSI_COLOR="0;31"
CPE_NAME="cpe:/o:centos:centos:8"
HOME_URL="https://centos.org/"
BUG_REPORT_URL="https://bugs.centos.org/"
CENTOS_MANTISBT_PROJECT="CentOS-8"
CENTOS_MANTISBT_PROJECT_VERSION="8"
(centos8) gilles@host:~$ id
uid=1000(gilles) gid=1000(gilles) groups=1000(gilles)
(centos8) gilles@host:~$ sudo id
[sudo] password for gilles:
uid=0(root) gid=0(root) groups=0(root)
(centos8) gilles@host:~$ xclock
^C
(centos8) gilles@host:~$ exit
exit
gilles@host:~$
Configuration
-------------
Configuration is done in `runon.conf` file, which describes supported
distribution in .INI format.
2021-04-30 20:21:55 +02:00
### Example config
2021-04-29 17:58:45 +02:00
```
[DEFAULT]
environment =
HOME
USER
DISPLAY
debian_chroot=${osname}
binds =
/etc/passwd:ro
/etc/group:ro
/etc/shadow:ro
/tmp/.X11-unix:ro
/home/${user}
[centos8]
dockerfile =
FROM centos:8
RUN yum install dnf-plugins-core -y
RUN yum config-manager --set-enabled powertools -y
RUN yum install sudo -y
RUN echo "Defaults lecture = never" >> /etc/sudoers
RUN echo "ALL ALL=(ALL) ALL" >> /etc/sudoers
pkginstall = RUN yum install {} -y
packages = ksh csh xterm xorg-x11-apps xkeyboard-config git
[debian9]
dockerfile =
FROM debian:9
RUN apt-get update
RUN apt-get -y install sudo
RUN echo "Defaults lecture = never" >> /etc/sudoers
pkginstall = RUN apt-get -y install {}
packages = ksh csh xterm x11-apps libgtk-3-0 build-essential git
```
Each section `[osname]` defines a distribution which can be used by runon.
The `[DEFAULT]` section defines default values which is used if not
overriden in individual section.
2021-04-30 20:21:55 +02:00
### Config entries
2021-04-29 17:58:45 +02:00
* `dockerfile` the base content of dockerfile which will be used to
generate the running environment. There is usually no need to diverge
2021-04-30 20:35:17 +02:00
from the ones given in example.
2021-04-29 17:58:45 +02:00
* `pkginstall` the dockerfile command used to install a package, likely
to be standard for all `deb` and `rpm` based distributions. In the
command `{}` is replaced by the package name.
* `packages` the list of packages to install. Feel free to add the ones
you need for your commands (likely news system libs, new tools, ...)
* `binds` the list of files and directories from the host system to
expose in the container system. you might want to add `/opt` or other
2021-04-30 20:35:17 +02:00
shared directories. See below for a description of `binds` entries
2021-04-29 17:58:45 +02:00
* `environment` the list of environment variables you want to pass or
set in the container system. See below for a description
Lines starting with `#` or `;` are comments.
Some substitution happens upon reading the configuration:
* `${user}` the current username
* `${osname}` the executed distribution.
2021-04-30 20:21:55 +02:00
### Binds
2021-04-29 17:58:45 +02:00
Each `binds` line can have one of the following formats:
<hostpath>
2021-04-30 20:35:17 +02:00
<hostpath>:<mode>
<hostpath>:<containerpath>
<hostpath>:<containerpath>:<mode>
2021-04-29 17:58:45 +02:00
with:
* `<hostpath>` is the filename or the dirname of the path you want
to expose
* `<containerpath>` is the pathname inside the container, by default
it's the same path.
* `<mode>` can be `rw`, read-write (by default), or `ro`, read-only.
2021-04-30 20:21:55 +02:00
### Environment
2021-04-29 17:58:45 +02:00
Each `environment` line define a Environment Variable which is set
in the container upon execution.
Each line can have one of the following formats:
<envvar>
<envvar>=<value>
If no value is given, the host value is passed into the container.