ybox 0.9.8.1__py3-none-any.whl → 0.9.11__py3-none-any.whl

ybox/env.py

@@ -60,34 +60,41 @@ class Environ:
         :param home_dir: if a non-default user home directory has to be set
         """
         self._home_dir = home_dir or os.path.expanduser("~")
+        self._home_dir = self._home_dir.rstrip("/")
         self._docker_cmd = docker_cmd or get_docker_command()
         cmd_version = subprocess.check_output([self._docker_cmd, "--version"])
         self._uses_podman = "podman" in cmd_version.decode("utf-8").lower()
         # local user home might be in a different location than /home but target user in the
         # container will always be in /home with podman else /root for the root user with docker
         # as ensured by entrypoint-base.sh script
-        target_uid = 0
+        current_user = getpass.getuser()
+        current_uid = pwd.getpwnam(current_user).pw_uid
         if self._uses_podman:
-            self._target_user = getpass.getuser()
-            target_uid = pwd.getpwnam(self._target_user).pw_uid
+            self._target_user = current_user
+            target_uid = current_uid
             self._target_home = f"/home/{self._target_user}"
         else:
             self._target_user = "root"
+            target_uid = 0
             self._target_home = "/root"
             # confirm that docker is being used in rootless mode (not required for podman because
             #   it runs as rootless when run by a non-root user in any case without explicit sudo
             #   which the ybox tools don't use)
             if (docker_ctx := subprocess.check_output(
                     [self._docker_cmd, "context", "show"]).decode("utf-8")).strip() != "rootless":
-                raise NotSupportedError("docker should use the rootless mode (see "
-                                        "https://docs.docker.com/engine/security/rootless/) "
-                                        f"but the current context is '{docker_ctx}'")
+                # check for DOCKER_HOST environment variable
+                expected_docker_host = f"unix:///run/user/{current_uid}/docker.sock"
+                if not docker_ctx or os.environ.get("DOCKER_HOST", "") != expected_docker_host:
+                    raise NotSupportedError("docker should use the rootless mode (see "
+                                            "https://docs.docker.com/engine/security/rootless/) "
+                                            f"but the current context is '{docker_ctx}' and "
+                                            f"$DOCKER_HOST is not set to '{expected_docker_host}'")
         os.environ["TARGET_HOME"] = self._target_home
         self._user_base = user_base = site.getuserbase()
         target_user_base = f"{self._target_home}/.local"
         self._data_dir = f"{user_base}/share/ybox"
         self._target_data_dir = f"{target_user_base}/share/ybox"
-        self._xdg_rt_dir = os.environ.get("XDG_RUNTIME_DIR", "")
+        self._xdg_rt_dir = os.environ.get("XDG_RUNTIME_DIR", "").rstrip("/")
         # the container user's one can be different because it is the root user for docker
         self._target_xdg_rt_dir = f"/run/user/{target_uid}"
         self._now = datetime.now()
@@ -148,6 +155,10 @@ class Environ:
         """if podman is the container manager being used"""
         return self._uses_podman
 
+    def systemd_user_conf_dir(self) -> str:
+        """standard configuration directory location of user specific systemd services"""
+        return f"{self._home_dir}/.config/systemd/user"
+
     @property
     def target_user(self) -> str:
         """username of the container user (which is the same as the current user for podman

ybox/migrate/{0.9.0-0.9.7:0.9.8.py → 0.9.0-0.9.10:0.9.11.py}

@@ -20,11 +20,12 @@ copy_ybox_scripts_to_container(static_conf, distro_conf)
 
 # rename PKGMGR_CLEANUP to PKGMGR_CLEAN in pkgmgr.conf
 scripts_dir = static_conf.scripts_dir
-pkgmgr_conf = f"{scripts_dir}/pkgmgr.conf"
-with open(pkgmgr_conf, "r", encoding="utf-8") as pkgmgr_file:
-    pkgmgr_data = pkgmgr_file.read()
-with open(pkgmgr_conf, "w", encoding="utf-8") as pkgmgr_file:
-    pkgmgr_file.write(pkgmgr_data.replace("PKGMGR_CLEANUP", "PKGMGR_CLEAN"))
+pkgmgr_conf = Path(f"{scripts_dir}/pkgmgr.conf")
+if pkgmgr_conf.exists():
+    with pkgmgr_conf.open("r", encoding="utf-8") as pkgmgr_file:
+        pkgmgr_data = pkgmgr_file.read()
+    with pkgmgr_conf.open("w", encoding="utf-8") as pkgmgr_file:
+        pkgmgr_file.write(pkgmgr_data.replace("PKGMGR_CLEANUP", "PKGMGR_CLEAN"))
 # run entrypoint-root.sh again to refresh scripts and configuration
 subprocess.run([static_conf.env.docker_cmd, "exec", "-it", static_conf.box_name, "/usr/bin/sudo",
                 "/bin/bash", f"{static_conf.target_scripts_dir}/entrypoint-root.sh"])

ybox/pkg/clean.py

@@ -8,14 +8,10 @@ from configparser import SectionProxy
 from ybox.cmd import PkgMgr, build_shell_command, run_command
 from ybox.config import StaticConfiguration
 from ybox.print import print_info
-from ybox.state import RuntimeConfiguration, YboxStateManagement
 
 
-# noinspection PyUnusedLocal
 def clean_cache(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
-                conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
-                state: YboxStateManagement) -> int:
-    # pylint: disable=unused-argument
+                conf: StaticConfiguration) -> int:
     """
     Clean package cache and related intermediate files.
 
@@ -23,8 +19,6 @@ def clean_cache(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
     :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
     :param docker_cmd: the podman/docker executable to use
     :param conf: the :class:`StaticConfiguration` for the container
-    :param runtime_conf: the `RuntimeConfiguration` of the container
-    :param state: instance of `YboxStateManagement` having the state of all ybox containers
     :return: integer exit status of clean command where 0 represents success
     """
     print_info(f"Cleaning package cache in container '{conf.box_name}'")

ybox/pkg/info.py

@@ -8,14 +8,10 @@ from configparser import SectionProxy
 
 from ybox.cmd import PkgMgr, page_command
 from ybox.config import StaticConfiguration
-from ybox.state import RuntimeConfiguration, YboxStateManagement
 
 
-# noinspection PyUnusedLocal
 def info_packages(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
-                  conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
-                  state: YboxStateManagement) -> int:
-    # pylint: disable=unused-argument
+                  conf: StaticConfiguration) -> int:
     """
     Show detailed information of an installed or repository package(s).
 
@@ -23,8 +19,6 @@ def info_packages(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: st
     :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
     :param docker_cmd: the podman/docker executable to use
     :param conf: the :class:`StaticConfiguration` for the container
-    :param runtime_conf: the `RuntimeConfiguration` of the container
-    :param state: instance of `YboxStateManagement` having the state of all ybox containers
     :return: integer exit status of info command where 0 represents success
     """
     quiet_flag = pkgmgr[PkgMgr.QUIET_DETAILS_FLAG.value] if args.quiet else ""

ybox/pkg/inst.py

@@ -24,10 +24,18 @@ from ybox.state import (CopyType, DependencyType, RuntimeConfiguration,
 from ybox.util import check_package, ini_file_reader, select_item_from_menu
 
 # match both "Exec=" and "TryExec=" lines (don't capture trailing newline)
-_EXEC_RE = re.compile(r"^(\s*(Try)?Exec\s*=\s*)(\S+)\s*(.*?)\s*$")
+_EXEC_PATTERN = r"\s*((Try)?Exec\s*=\s*)(\S+)\s*(.*?)\s*"
+# pattern to match icons with absolute paths and change them to just names
+_ICON_PATH_PATTERN = r"\s*Icon\s*=\s*(/usr/share/(icons|pixmaps)/\S+)\s*"
+# regex to match either of the two above
+_EXEC_ICON_RE = re.compile(f"^{_EXEC_PATTERN}|{_ICON_PATH_PATTERN}$")
 # match !p and !a to replace executable program (third group above) and arguments respectively
 _FLAGS_RE = re.compile("![ap]")
-_LOCAL_BIN_DIRS = ["/usr/bin", "/bin", "/usr/sbin", "/sbin", "/usr/local/bin", "/usr/local/sbin"]
+# environment variables passed through from host environment to podman/docker executable
+_PASSTHROUGH_ENVVARS = ("XAUTHORITY", "DISPLAY", "WAYLAND_DISPLAY", "FREETYPE_PROPERTIES",
+                        "SSH_AUTH_SOCK", "GPG_AGENT_INFO",
+                        "__NV_PRIME_RENDER_OFFLOAD", "__GLX_VENDOR_LIBRARY_NAME",
+                        "__VK_LAYER_NV_optimus", "VK_ICD_FILES", "VK_ICD_FILENAMES")
 
 
 def install_package(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
@@ -153,7 +161,10 @@ def _install_package(package: str, args: argparse.Namespace, install_cmd: str, l
             if not skip_desktop_files:
                 copy_type |= CopyType.DESKTOP
             if not skip_executables:
-                copy_type |= CopyType.EXECUTABLE
+                resp = input("Create wrapper(s) for application executable(s) of package "
+                             f"'{package}'? (Y/n) ") if quiet == 0 else "Y"
+                if resp.strip().lower() != "n":
+                    copy_type |= CopyType.EXECUTABLE
         # TODO: wrappers for newly installed required dependencies should also be created;
         #       handle DependencyType.SUGGESTION if supported by underlying package manager
         app_flags: dict[str, str] = {}
@@ -223,13 +234,14 @@ def get_optional_deps(package: str, docker_cmd: str, container_name: str,
     #  2) redirect PKG: lines somewhere else like a common file: this can be done but will
     #          likely be more messy than the code below (e.g. handle concurrent executions),
     #          but still can be considered in future
+    # (reduced bufsize to show download progress better)
     with subprocess.Popen(build_shell_command(
             docker_cmd, container_name, f"{opt_deps_cmd} {package}"),
-            stdout=subprocess.PIPE) as deps_result:
+            bufsize=256, stdout=subprocess.PIPE) as deps_result:
         line = bytearray()
         # possible end of lines
-        eol1 = b"\r"[0]
-        eol2 = b"\n"[0]
+        eol1 = ord(b"\r")
+        eol2 = ord(b"\n")
         buffered = 0
         assert deps_result.stdout is not None
         # readline does not work for in-place updates like from aria2
@@ -245,7 +257,7 @@ def get_optional_deps(package: str, docker_cmd: str, container_name: str,
                     break
             else:
                 line.append(char[0])
-                if buffered >= 4:  # flush frequently to show download progress, for example
+                if buffered >= 8:  # flush frequently to show download progress, for example
                     sys.stdout.flush()
                     buffered = 0
         sys.stdout.flush()
@@ -419,7 +431,7 @@ def docker_cp_action(docker_cmd: str, box_name: str, src: str,
     with tempfile.TemporaryDirectory() as temp_dir:
         # use shell pipe and tar instead of python Popen and tarfile which will require much more
         # code unncessarily and may not be able to use `run_command`
-        shell_cmd = (f"'{docker_cmd}' exec '{box_name}' tar -C '{src_dir}' -cpf - '{src_file}' | "
+        shell_cmd = (f"'{docker_cmd}' exec '{box_name}' tar -C '{src_dir}' -chpf - '{src_file}' | "
                      f"tar -C '{temp_dir}' -xpf -")
         if (code := int(run_command(["/bin/sh", "-c", shell_cmd], exit_on_error=False,
                                     error_msg=f"copying of file from '{box_name}:{src}'"))) == 0:
@@ -430,9 +442,9 @@ def docker_cp_action(docker_cmd: str, box_name: str, src: str,
 def _wrap_desktop_file(filename: str, file: str, docker_cmd: str, conf: StaticConfiguration,
                        app_flags: dict[str, str], wrapper_files: list[str]) -> None:
     """
-    For a desktop file, add "podman/docker exec ..." to its Exec/TryExec lines. Also read
-    the additional flags for the command passed in `app_flags` and add them to an appropriate
-    position in the Exec/TryExec lines.
+    For a desktop file, add "podman/docker exec ..." to its `Exec` lines. Also read the additional
+    flags for the command passed in `app_flags` and add them to an appropriate position in the
+    `Exec` lines. Also removes the `TryExec` lines that do not work in some desktop environments.
 
     :param filename: name of the desktop file being wrapped
     :param file: full path of the desktop file being wrapped
@@ -445,7 +457,13 @@ def _wrap_desktop_file(filename: str, file: str, docker_cmd: str, conf: StaticCo
     # container name is added to desktop file to make it unique
     wrapper_name = f"ybox.{conf.box_name}.{filename}"
 
-    def replace_executable(match: re.Match[str]) -> str:
+    def replace_exec_icon(match: re.Match[str]) -> str:
+        """replace Exec, TryExec and Icon lines appropriately for the host system"""
+        if not (exec_word := match.group(1)):  # check for the case of `Icon=/usr/...`
+            return f"Icon={os.path.basename(match.group(5))}\n"
+        # remove TryExec lines that don't work in some desktop environments (like KDE plasma 5)
+        if match.group(2):
+            return ""
         program = match.group(3)
         args = match.group(4)
         # check for additional flags to be added
@@ -457,9 +475,9 @@ def _wrap_desktop_file(filename: str, file: str, docker_cmd: str, conf: StaticCo
         else:
             full_cmd = program
         # pseudo-tty cannot be allocated with rootless docker outside of a terminal app
-        return (f'{match.group(1)}{docker_cmd} exec -e=XAUTHORITY -e=DISPLAY '
-                f'-e=FREETYPE_PROPERTIES {conf.box_name} /usr/local/bin/run-in-dir '
-                f'"" {full_cmd}\n')
+        env_vars = " -e=".join(_PASSTHROUGH_ENVVARS)
+        return (f'{exec_word}{docker_cmd} exec -e={env_vars} {conf.box_name} '
+                f'/usr/local/bin/run-in-dir "" {full_cmd}\n')
 
     # the destination will be $HOME/.local/share/applications
     os.makedirs(conf.env.user_applications_dir, mode=Consts.default_directory_mode(),
@@ -470,7 +488,7 @@ def _wrap_desktop_file(filename: str, file: str, docker_cmd: str, conf: StaticCo
     def write_desktop_file(src: str) -> None:
         with open(wrapper_file, "w", encoding="utf-8") as wrapper_fd:
             with open(src, "r", encoding="utf-8") as src_fd:
-                wrapper_fd.writelines(_EXEC_RE.sub(replace_executable, line) for line in src_fd)
+                wrapper_fd.writelines(_EXEC_ICON_RE.sub(replace_exec_icon, line) for line in src_fd)
     if docker_cp_action(docker_cmd, conf.box_name, file, write_desktop_file) == 0:
         wrapper_files.append(wrapper_file)
 
@@ -539,8 +557,8 @@ def _copy_app_icons(selected_icons: dict[str, tuple[float, str]], docker_cmd: st
         # copy from temporary file over the existing one, if any, to overwrite rather than move
         # (which will preserve all of its hard links, for example)
         exists = os.path.exists(target_icon_path)
-        if docker_cp_action(docker_cmd, conf.box_name, icon_path,
-                            lambda src, dest=target_icon_path: shutil.copy2(src, dest)) == 0:
+        if docker_cp_action(docker_cmd, conf.box_name, icon_path, lambda src, dest=target_icon_path:
+                            None if shutil.copy2(src, dest) else None) == 0:  # "if" for pyright
             # skip registration of icon file it already existed and was overwritten so that
             # it is not removed on package uninstall
             if not exists:
@@ -568,9 +586,9 @@ def _can_wrap_executable(filename: str, file: str, conf: StaticConfiguration, qu
             print_warn(f"Skipping local wrapper for {file}")
             return False
     # also check if creating user executable will override system executable
-    for bin_dir in _LOCAL_BIN_DIRS:
+    for bin_dir in Consts.sys_bin_dirs():
         sys_exec = f"{bin_dir}/{filename}"
-        if os.path.exists(sys_exec):
+        if os.access(sys_exec, os.X_OK):
             resp = input(f"Target file {wrapper_exec} will override system installed "
                          f"{sys_exec}. Continue? (y/N) ") if quiet < 2 else "N"
             if resp.strip().lower() != "y":
@@ -604,9 +622,9 @@ def _wrap_executable(filename: str, file: str, docker_cmd: str, conf: StaticConf
             lambda f_match: _replace_flags(f_match, flags, f'"{file}"', '"$@"'), flags)
     else:
         full_cmd = f'/usr/local/bin/run-in-dir "`pwd`" "{file}" "$@"'
+    env_vars = " -e=".join(_PASSTHROUGH_ENVVARS)
     exec_content = ("#!/bin/sh\n",
-                    f"exec {docker_cmd} exec -it -e=XAUTHORITY -e=DISPLAY "
-                    f"-e=FREETYPE_PROPERTIES {conf.box_name} ", full_cmd)
+                    f"exec {docker_cmd} exec -it -e={env_vars} {conf.box_name} ", full_cmd)
     with open(wrapper_exec, "w", encoding="utf-8") as wrapper_fd:
         wrapper_fd.writelines(exec_content)
     os.chmod(wrapper_exec, mode=0o755, follow_symlinks=True)

ybox/pkg/list.py

@@ -164,11 +164,8 @@ def _format_long_line(line: str, separator: str, dep_of_width: int,
     return name, version, dep_of, description
 
 
-# noinspection PyUnusedLocal
 def list_files(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
-               conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
-               state: YboxStateManagement) -> int:
-    # pylint: disable=unused-argument
+               conf: StaticConfiguration) -> int:
     """
     List the files of a package installed in a container including those not managed by `ybox-pkg`.
 
@@ -176,8 +173,6 @@ def list_files(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
     :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
     :param docker_cmd: the podman/docker executable to use
     :param conf: the :class:`StaticConfiguration` for the container
-    :param runtime_conf: the `RuntimeConfiguration` of the container
-    :param state: instance of `YboxStateManagement` having the state of all ybox containers
     :return: integer exit status of list package files command where 0 represents success
     """
     package: str = args.package

ybox/pkg/mark.py

@@ -30,7 +30,7 @@ def mark_package(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str
     mark_explicit: bool = args.explicit
     mark_dependency_of: str = args.dependency_of or ""
     if not mark_explicit ^ bool(mark_dependency_of):
-        print_error("ybox-pkg mark: exactly one of -e or -D option must be specified "
+        print_error("ybox-pkg mark: exactly one of -e or -d option must be specified "
                     f"(explicit={mark_explicit}, dependency-of={mark_dependency_of})")
         return 1
     # check that the package(s) are installed and replace with actual installed name

ybox/pkg/repair.py

@@ -14,6 +14,10 @@ from ybox.print import (fgcolor, print_color, print_error, print_info,
                         print_warn)
 from ybox.state import RuntimeConfiguration, YboxStateManagement
 
+# TODO: SW: repair should work even if no containers are active (just remove the locks)
+# Also, just checking lock file existing lock file existence is not enough (e.g. for dpkg/apt)
+# and may need to check if they are locked by any process after kill so define this in distro.ini
+
 
 def repair_package_state(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
                          conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,

ybox/pkg/search.py

@@ -8,14 +8,10 @@ from configparser import SectionProxy
 
 from ybox.cmd import PkgMgr, page_command
 from ybox.config import StaticConfiguration
-from ybox.state import RuntimeConfiguration, YboxStateManagement
 
 
-# noinspection PyUnusedLocal
 def search_packages(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd: str,
-                    conf: StaticConfiguration, runtime_conf: RuntimeConfiguration,
-                    state: YboxStateManagement) -> int:
-    # pylint: disable=unused-argument
+                    conf: StaticConfiguration) -> int:
     """
     Uninstall package specified by `args.package` on a ybox container with given podman/docker
     command. Additional flags honored are `args.quiet` to bypass user confirmation during
@@ -27,8 +23,6 @@ def search_packages(args: argparse.Namespace, pkgmgr: SectionProxy, docker_cmd:
     :param pkgmgr: the `[pkgmgr]` section from `distro.ini` configuration file of the distribution
     :param docker_cmd: the podman/docker executable to use
     :param conf: the :class:`StaticConfiguration` for the container
-    :param runtime_conf: the `RuntimeConfiguration` of the container
-    :param state: instance of `YboxStateManagement` having the state of all ybox containers
     :return: integer exit status of search command where 0 represents success
     """
     quiet_flag = pkgmgr[PkgMgr.QUIET_DETAILS_FLAG.value] if args.quiet else ""

ybox/run/cmd.py

@@ -5,7 +5,7 @@ Code for the `ybox-cmd` script that is used to execute programs in an active ybo
 import argparse
 import sys
 
-from ybox.cmd import run_command
+from ybox.cmd import parser_version_check, run_command
 from ybox.env import get_docker_command
 
 
@@ -51,4 +51,5 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
     parser.add_argument("container_name", type=str, help="name of the active ybox")
     parser.add_argument("command", nargs="*", default="/bin/bash",
                         help="run the given command (default is /bin/bash)")
+    parser_version_check(parser, argv)
     return parser.parse_args(argv)

ybox/run/control.py

@@ -6,51 +6,70 @@ import argparse
 import sys
 import time
 
-from ybox.cmd import check_active_ybox, get_ybox_state, run_command
+from ybox.cmd import (check_active_ybox, get_ybox_state, parser_version_check,
+                      run_command)
 from ybox.config import StaticConfiguration
 from ybox.env import Environ, get_docker_command
 from ybox.print import fgcolor, print_color, print_error
 from ybox.util import wait_for_ybox_container
 
+# TODO: SW: add backup/restore of the running image with the option to backup $HOME of the
+# container user, and shared root warning if it is being used
+
 
 def main() -> None:
     """main function for `ybox-control` script"""
     main_argv(sys.argv[1:])
 
 
-def start_container(docker_cmd: str, container_name: str):
+def start_container(docker_cmd: str, args: argparse.Namespace):
     """
     Start an existing ybox container.
 
     :param docker_cmd: the podman/docker executable to use
-    :param container_name: name of the container
+    :param args: arguments having all attributes passed by the user
     """
+    container_name = args.container
     if status := get_ybox_state(docker_cmd, container_name, (), exit_on_error=False):
         if status[0] == "running":
-            print_color(f"Ybox container '{container_name}' already active", fg=fgcolor.cyan)
+            print_color(f"ybox container '{container_name}' already active", fg=fgcolor.cyan)
         else:
             print_color(f"Starting ybox container '{container_name}'", fg=fgcolor.cyan)
             run_command([docker_cmd, "container", "start", container_name],
                         error_msg="container start")
             conf = StaticConfiguration(Environ(docker_cmd), status[1], container_name)
-            wait_for_ybox_container(docker_cmd, conf)
+            wait_for_ybox_container(docker_cmd, conf, args.timeout)
     else:
         print_error(f"No ybox container '{container_name}' found")
         sys.exit(1)
 
 
-def stop_container(docker_cmd: str, container_name: str, fail_on_error: bool):
+def stop_container(docker_cmd: str, args: argparse.Namespace):
     """
-    Stop a ybox container.
+    Stop an active ybox container.
+
+    :param docker_cmd: the podman/docker executable to use
+    :param args: arguments having all attributes passed by the user
+    """
+    _stop_container(docker_cmd, args.container, args.timeout,
+                    fail_on_error=not args.ignore_stopped)
+
+
+def _stop_container(docker_cmd: str, container_name: str, timeout: int,
+                    fail_on_error: bool):
+    """
+    Stop an active ybox container.
 
     :param docker_cmd: the podman/docker executable to use
     :param container_name: name of the container
+    :param timeout: seconds to wait for container to stop before killing the container
     :param fail_on_error: if True then show error message on failure to stop else ignore
     """
     if check_active_ybox(docker_cmd, container_name):
         print_color(f"Stopping ybox container '{container_name}'", fg=fgcolor.cyan)
-        run_command([docker_cmd, "container", "stop", container_name], error_msg="container stop")
-        for _ in range(120):
+        run_command([docker_cmd, "container", "stop", "-t", str(timeout), container_name],
+                    error_msg="container stop")
+        for _ in range(timeout * 2):
             time.sleep(0.5)
             if get_ybox_state(docker_cmd, container_name, ("exited", "stopped"),
                               exit_on_error=False, state_msg=" stopped"):
@@ -63,6 +82,42 @@ def stop_container(docker_cmd: str, container_name: str, fail_on_error: bool):
         print_color(f"No active ybox container '{container_name}' found", fg=fgcolor.cyan)
 
 
+def restart_container(docker_cmd: str, args: argparse.Namespace):
+    """
+    Restart an existing ybox container.
+
+    :param docker_cmd: the podman/docker executable to use
+    :param args: arguments having all attributes passed by the user
+    """
+    _stop_container(docker_cmd, args.container, timeout=int(args.timeout / 2), fail_on_error=False)
+    start_container(docker_cmd, args)
+
+
+def show_container_status(docker_cmd: str, args: argparse.Namespace) -> None:
+    """
+    Show container status which will be a string like running/exited.
+
+    :param docker_cmd: the podman/docker executable to use
+    :param args: arguments having all attributes passed by the user
+    """
+    container_name = args.container
+    if status := get_ybox_state(docker_cmd, container_name, (), exit_on_error=False):
+        print(status[0])
+    else:
+        print_error(f"No ybox container '{container_name}' found")
+
+
+def wait_for_container_stop(docker_cmd: str, args: argparse.Namespace) -> None:
+    """
+    Wait for an active container to stop.
+
+    :param docker_cmd: the podman/docker executable to use
+    :param args: arguments having all attributes passed by the user
+    """
+    while check_active_ybox(docker_cmd, args.container):
+        time.sleep(2)
+
+
 def main_argv(argv: list[str]) -> None:
     """
     Main entrypoint of `ybox-control` that takes a list of arguments which are usually the
@@ -73,19 +128,7 @@ def main_argv(argv: list[str]) -> None:
     """
     args = parse_args(argv)
     docker_cmd = get_docker_command()
-    container_name = args.container_name
-    if args.action == "start":
-        start_container(docker_cmd, container_name)
-    elif args.action == "stop":
-        stop_container(docker_cmd, container_name, fail_on_error=True)
-    elif args.action == "restart":
-        stop_container(docker_cmd, container_name, fail_on_error=False)
-        start_container(docker_cmd, container_name)
-    elif args.action == "status":
-        if status := get_ybox_state(docker_cmd, container_name, (), exit_on_error=False):
-            print(status[0])
-        else:
-            print_error(f"No ybox container '{container_name}' found")
+    args.func(docker_cmd, args)
 
 
 def parse_args(argv: list[str]) -> argparse.Namespace:
@@ -96,7 +139,46 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
     :return: the result of parsing using the `argparse` library as a :class:`argparse.Namespace`
     """
     parser = argparse.ArgumentParser(description="control ybox containers")
-    parser.add_argument("action", choices=["start", "stop", "restart", "status"],
-                        help="action to perform")
-    parser.add_argument("container_name", help="name of the ybox")
+    operations = parser.add_subparsers(title="Operations", required=True, metavar="OPERATION",
+                                       help="DESCRIPTION")
+
+    start = operations.add_parser("start", help="start a ybox container")
+    _add_subparser_args(start, 60, "time in seconds to wait for a container to start")
+    start.set_defaults(func=start_container)
+
+    stop = operations.add_parser("stop", help="stop a ybox container")
+    _add_subparser_args(stop, 10,
+                        "time in seconds to wait for a container to stop before killing it")
+    stop.add_argument("-I", "--ignore-stopped", action="store_true",
+                      help="don't fail on an already stopped container")
+    stop.set_defaults(func=stop_container)
+
+    restart = operations.add_parser("restart", help="restart a ybox container")
+    _add_subparser_args(restart, 60, "time in seconds to wait for a container to restart")
+    restart.set_defaults(func=restart_container)
+
+    status = operations.add_parser("status", help="show status of a ybox container")
+    _add_subparser_args(status, 0, "")
+    status.set_defaults(func=show_container_status)
+
+    wait = operations.add_parser("wait", help="wait for an active ybox container to stop")
+    _add_subparser_args(wait, 0, "")
+    wait.set_defaults(func=wait_for_container_stop)
+
+    parser_version_check(parser, argv)
     return parser.parse_args(argv)
+
+
+def _add_subparser_args(subparser: argparse.ArgumentParser, timeout_default: int,
+                        timeout_help: str) -> None:
+    """
+    Add arguments for the sub-operation of the ybox-control command.
+
+    :param subparser: the :class:`argparse.ArgumentParser` object for the sub-command
+    :param timeout_default: default value for the -t/--timeout argument, or 0 to skip the argument
+    :param timeout_help: help string for the -t/--timeout argument
+    """
+    if timeout_default != 0:
+        subparser.add_argument("-t", "--timeout", type=int, default=timeout_default,
+                               help=timeout_help)
+    subparser.add_argument("container", help="name of the ybox")