Skip to content

Latest commit

 

History

History
291 lines (212 loc) · 7.83 KB

ish.1.adoc

File metadata and controls

291 lines (212 loc) · 7.83 KB

ish(1) Manual Page

NAME

ish - run a shell ready to emulate the syscall chroot(2) for unprivileged users.

SYNOPSIS

ish [OPTIONS] [--] [SCRIPT_FILE [ARGS…​]]

ish [OPTIONS] [--] -c COMMAND [NAME [ARGS…​]]

ish [OPTIONS] [--] -s [ARGS…​]

DESCRIPTION

Runs the command process in an iamroot environment ready to emulate the chroot(2) syscall for unprivileged users.

When called without arguments, ish defaults to running an interactive shell.

Under the hood, ish preloads a library which intercepts some libc(7) functions to emulates chroot(2) in a pure unprivileged process.

For a more thorough description of sh(1), bash(1), zsh(1) or any other shells, please refers to their manuals.

OPTIONS

POSIX Shell related options

-c

Read commands from command-line.

-i

Set interactive.

-s

Read commands from standard-input.

iamroot specific options

--login

Act as if it had been invoked as a login shell.

--root DIR

Absolute path to the root directory to chroot in.

--profile-file FILE

Execute initialization file from FILE.

--rc-file FILE

Execute commands from FILE.

--multiarch

Use multiarch library path in chroot.

--libdir

Set /lib:/usr/lib as default library path in chroot.

--deflib PATH

Default library path to use in chroot.

--exec FILE

Absolute path to the iamroot exec script to use.

--library LIB

Absolute path to the iamroot library to use.

--shell SHELL

Set shell interpretor.

--no-color

Turn off color.

--debug

Turn on debug mode.

--debug-fd FD

Set debug fd.

--debug-ignore REGEX

Regular expression of functions to ignore in debug mode. Does not imply --debug.

--exec-ignore REGEX

Regular expression of executable path to ignore at execve().

--path-resolution-ignore REGEX

Regular expression of path to ignore for path resolution in chroot.

--version

Print version.

--help

Print usage.

ENVIRONMENT VARIABLES

SHELL

The shell interpreter to use.

ISHLVL

Incremented by one each time an instance of ish is started.

IAMROOT_ROOT

Set absolute path to root directory to chroot in. Equivalent to --root DIR.

ISH_PROFILE_FILE

Set path to initialization file. Equivalent to --profile-file FILE.

ISH_RC_FILE

Set path to command file. Equivalent to --rc-file FILE.

IAMROOT_MULTIARCH

Use multiarch default library path in chroot. Equivalent to --multiarch.

IAMROOT_DEFLIB

Set default library path to use in chroot. Equivalent to --deflib PATH.

IAMROOT_EXEC

Set absolute path to exec script to use. Equivalent to --exec EXEC.

IAMROOT_LIB

Set absolute path to library to use. Equivalent to --library LIB.

IAMROOT_DEBUG

Turn on debug mode. Equivalent to --debug.

IAMROOT_DEBUG_FD

Set debug fd. Equivalent to --debug-fd.

IAMROOT_DEBUG_IGNORE

Set functions to ignore in debug mode. Equivalent to --debug-ignore REGEX.

IAMROOT_EXEC_IGNORE

Set executable path to ignore in execve(). Equivalent to --exec-ignore REGEX.

IAMROOT_PATH_RESOLUTION_IGNORE

Set path to ignore for path resolution in chroot. Equivalent to --path-resolution-ignore REGEX.

EXAMPLES

Run an interactive shell in an iamroot environment

[gportay@archlinux ~]$ ish
[root@archlinux ~]#

Print effective user name

[root@archlinux ~]# whoami
root

Change root directory via chroot(1)

[gportay@archlinux ~]$ mkdir -p alpine-minirootfs
[gportay@archlinux ~]$ wget http://dl-cdn.alpinelinux.org/alpine/v3.13/releases/x86_64/alpine-minirootfs-3.13.0-x86_64.tar.gz
[gportay@archlinux ~]$ tar xf alpine-minirootfs-3.13.0-x86_64.tar.gz -C alpine-minirootfs
[gportay@archlinux ~]$ ish
[root@archlinux ~]# chroot alpine-minirootfs /bin/ash
/ # cat /etc/os-release
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.13.0
PRETTY_NAME="Alpine Linux v3.13"
HOME_URL="https://alpinelinux.org/"
BUG_REPORT_URL="https://bugs.alpinelinux.org/"
/ # sh --help
BusyBox v1.32.1 () multi-call binary.
Usage: sh [-/+OPTIONS] [-/+o OPT]... [-c 'SCRIPT' [ARG0 [ARGS]] / FILE [ARGS] / -s [ARGS]]
Unix shell interpreter
/ # ls /proc/self/cwd -l
lrwxrwxrwx    1 root     root             0 Mar 24 20:53 /proc/self/cwd -> /
       / # ls -l /proc/self/root
lrwxrwxrwx    1 root     root             0 Mar 24 20:53 /proc/self/root -> /

Create a new Arch Linux system installation from scratch via pacstrap(8)

[gportay@archlinux ~]$ mkdir -p rootfs
[gportay@archlinux ~]$ ish -c "pacstrap -GM rootfs"
==> Creating install root at rootfs
==> Installing packages to rootfs
(...)
:: Running post-transaction hooks...
( 1/10) Creating system user accounts...
( 2/10) Updating journal message catalog...
( 3/10) Reloading system manager configuration...
  Skipped: Running in chroot.
( 4/10) Updating udev hardware database...
( 5/10) Applying kernel sysctl settings...
  Skipped: Running in chroot.
( 6/10) Creating temporary files...
( 7/10) Reloading device manager configuration...
  Skipped: Running in chroot.
( 8/10) Arming ConditionNeedsUpdate...
( 9/10) Rebuilding certificate stores...
(10/10) Reloading system bus configuration...
  Skipped: Running in chroot.

Note: Some post-transaction hooks failed due to lack of privileges.

Change root directory via arch-chroot(8)

[gportay@archlinux ~]$ ish
[root@archlinux ~]# arch-chroot rootfs
==> ERROR: This script must be run with root privileges
[root@archlinux ~]# ls -l /proc/self/cwd
lrwxrwxrwx 1 root root 0 Apr 25 09:57 /proc/self/cwd -> /home/gportay
[root@archlinux ~]# ls -l /proc/self/root
lrwxrwxrwx 1 root root 0 Apr 25 09:57 /proc/self/root -> /

Create a new Alpine Linux system installation from scratch via alpine-make-rootfs

[gportay@archlinux ~]$ ish -c "alpine-make-rootfs alpine-rootfs --keys-dir /usr/share/apk/keys/x86_64 --mirror-uri http://dl-cdn.alpinelinux.org/alpine"
> Installing system
fetch http://dl-cdn.alpinelinux.org/alpine/latest-stable/main/x86_64/APKINDEX.tar.gz
fetch http://dl-cdn.alpinelinux.org/alpine/latest-stable/community/x86_64/APKINDEX.tar.gz
(1/8) Installing alpine-baselayout-data (3.4.3-r1)
(2/8) Installing musl (1.2.4-r0)
(3/8) Installing busybox (1.36.1-r0)
Executing busybox-1.36.1-r0.post-install
(4/8) Installing busybox-binsh (1.36.1-r0)
(5/8) Installing alpine-baselayout (3.4.3-r1)
Executing alpine-baselayout-3.4.3-r1.pre-install
Executing alpine-baselayout-3.4.3-r1.post-install
(6/8) Installing busybox-suid (1.36.1-r0)
(7/8) Installing scanelf (1.3.7-r1)
(8/8) Installing musl-utils (1.2.4-r0)
Executing busybox-1.36.1-r0.trigger
OK: 2 MiB in 8 packages
(1/2) Installing alpine-keys (2.4-r1)
(2/2) Installing alpine-release (3.18.0-r0)
OK: 2 MiB in 10 packages
> Cleaning-up rootfs

Change root directory via chroot(8)

[gportay@archlinux ~]$ ish
[root@archlinux ~]# ls -l /proc/self/cwd
lrwxrwxrwx 1 root root 0 Apr 25 09:54 /proc/self/cwd -> /home/gportay
[root@archlinux ~]# ls -l /proc/self/root
lrwxrwxrwx 1 root root 0 Apr 25 09:54 /proc/self/root -> /
[iamroot][root@archlinux ~]# chroot alpine-rootfs /bin/sh
/ # ls -l /proc/self/cwd
lrwxrwxrwx    1 root     root             0 Apr 25 09:54 /proc/self/cwd -> /
/ # ls -l /proc/self/root
lrwxrwxrwx    1 root     root             0 Apr 25 09:55 /proc/self/root -> /

AUTHOR

Written by Gaël PORTAY gael.portay@gmail.com

COPYRIGHT

Copyright (c) 2021-2024 Gaël PORTAY

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 2.1 of the License, or (at your option) any later version.

SEE ALSO

iamroot(7), sh(1), chroot(2)