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

ybox/run/create.py

@@ -18,15 +18,20 @@ from pathlib import Path
 from textwrap import dedent
 from typing import Optional
 
-from ybox.cmd import PkgMgr, RepoCmd, YboxLabel, check_ybox_exists, run_command
+from ybox import __version__ as product_version
+from ybox.cmd import (PkgMgr, RepoCmd, YboxLabel, check_ybox_exists,
+                      parser_version_check, run_command)
 from ybox.config import Consts, StaticConfiguration
 from ybox.env import Environ, NotSupportedError, PathName
 from ybox.filelock import FileLock
 from ybox.pkg.inst import install_package, wrap_container_files
 from ybox.print import (bgcolor, fgcolor, print_color, print_error, print_info,
-                        print_warn)
+                        print_notice, print_warn)
+from ybox.run.destroy import (get_all_containers, remove_orphans_from_db,
+                              ybox_systemd_service_prefix)
 from ybox.run.graphics import (add_env_option, add_mount_option, enable_dri,
-                               enable_nvidia, enable_wayland, enable_x11)
+                               enable_nvidia, enable_wayland, enable_x11,
+                               handle_variable_mount)
 from ybox.run.pkg import parse_args as pkg_parse_args
 from ybox.state import RuntimeConfiguration, YboxStateManagement
 from ybox.util import (EnvInterpolation, config_reader,
@@ -181,19 +186,30 @@ def main_argv(argv: list[str]) -> None:
 
     # set up the final container with all the required arguments
     print_info(f"Initializing container for '{distro}' using '{profile}'")
-    start_container(docker_full_args, current_user, shared_root, shared_root_dirs, conf)
+    run_container(docker_full_args, current_user, shared_root, shared_root_dirs, conf)
     print_info("Waiting for the container to initialize (see "
                f"'ybox-logs -f {box_name}' for detailed progress)")
     # wait for container to initialize while printing out its progress from conf.status_file
-    wait_for_ybox_container(docker_cmd, conf)
+    wait_for_ybox_container(docker_cmd, conf, 600)
 
     # remove distribution specific scripts and restart container the final time
-    print_info(f"Restarting the final container '{box_name}'")
+    print_info(f"Starting the final container '{box_name}'")
     Path(f"{conf.scripts_dir}/{Consts.entrypoint_init_done_file()}").touch(mode=0o644)
-    restart_container(docker_cmd, conf)
-    print_info("Waiting for the container to be ready (see "
-               f"'ybox-logs -f {box_name}' for detailed progress)")
-    wait_for_ybox_container(docker_cmd, conf)
+    wait_msg = ("Waiting for the container to be ready "
+                f"(see ybox-logs -f {box_name}' for detailed progress)")
+    if not args.skip_systemd_service and (sys_path := os.pathsep.join(Consts.sys_bin_dirs())) and (
+            systemctl := shutil.which("systemctl", path=sys_path)) and run_command(
+                [systemctl, "--user", "--quiet", "is-enabled", "default.target"],
+                exit_on_error=False) == 0:
+        create_and_start_service(box_name, env, systemctl, sys_path, wait_msg)
+    else:
+        if not args.skip_systemd_service:
+            print_warn("Skipping user systemd service generation due to missing systemctl in "
+                       f"PATH={os.pathsep.join(Consts.sys_bin_dirs())} or failure in "
+                       "'systemctl --user is-enabled default.target'")
+        start_container(docker_cmd, conf)
+        print_info(wait_msg)
+        wait_for_ybox_container(docker_cmd, conf, 120)
     # truncate the app.list and config.list files so that those actions are skipped if the
     # container is restarted later
     if os.access(conf.app_list, os.W_OK):
@@ -201,11 +217,17 @@ def main_argv(argv: list[str]) -> None:
     if os.access(conf.config_list, os.W_OK):
         truncate_file(conf.config_list)
 
+    # check and remove any dangling container references in state database
+    valid_containers = set(get_all_containers(docker_cmd))
+
     # finally add the state and register the installed packages that were reassigned to this
     # container (because the previously destroyed one has the same configuration and shared root)
     with YboxStateManagement(env) as state:
+        state.begin_transaction()
+        remove_orphans_from_db(valid_containers, state)
         owned_packages = state.register_container(box_name, distro, shared_root, box_conf,
                                                   args.force_own_orphans)
+        state.commit()
         # create wrappers for owned_packages
         if owned_packages:
             list_cmd = pkgmgr[PkgMgr.LIST_FILES.value]
@@ -254,6 +276,12 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
     parser.add_argument("-n", "--name", type=str,
                         help="name of the ybox; default is ybox-<distribution>_<profile> "
                              "if not provided (removing the .ini suffix from <profile> file)")
+    parser.add_argument("-S", "--skip-systemd-service", action="store_true",
+                        help="skip creation of user systemd service file for the ybox container; "
+                             "by default a user systemd service file is created and enabled in "
+                             "~/.config/systemd/user with the name 'ybox-<name>.service' if the "
+                             "<name> does not begin with 'ybox-' prefix else '<name>.service' if "
+                             "it already has 'ybox-' prefix")
     parser.add_argument("-F", "--force-own-orphans", action="store_true",
                         help="force ownership of orphan packages on the same shared root even "
                              "if container configuration does not match, meaning the packages "
@@ -262,7 +290,14 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
                              "container regardless of the container configuration")
     parser.add_argument("-C", "--distribution-config", type=str,
                         help="path to distribution configuration file to use instead of the "
-                             "`distro.ini` from user/system configuration paths")
+                             "'distro.ini' from user/system configuration paths")
+    parser.add_argument("--distribution-image", type=str,
+                        help="custom container image to use that overrides the one specified in "
+                             "the distribution's 'distro.ini'; note that the distribution "
+                             "configuration scripts make assumptions on the available utilities "
+                             "in the image so you should ensure that the provided image is "
+                             "compatible with and a superset of the base image specified in the "
+                             "builtin profile of the distribution in the installed version")
     parser.add_argument("-q", "--quiet", action="store_true",
                         help="proceed without asking any questions using defaults where possible; "
                              "this should usually be used with explicit specification of "
@@ -281,6 +316,7 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
                              "optional and user is presented with a selection menu of the "
                              "available profiles in the user or system profiles directory "
                              "whichever is found (in that order)")
+    parser_version_check(parser, argv)
     return parser.parse_args(argv)
 
 
@@ -363,7 +399,7 @@ def select_profile(args: argparse.Namespace, env: Environ) -> PathName:
     if len(profiles) == 1:
         print_info(f"Using profile '{profiles[0]}'")
         return profiles[0]
-    if len(profiles) == 0:
+    if not profiles:
         print_error(f"No valid profile found in '{profiles_dir}'")
         sys.exit(1)
 
@@ -491,6 +527,12 @@ def read_distribution_config(args: argparse.Namespace,
         distro_conf_file, only_sys_conf=True), env_interpolation)
     distro_base_section = distro_config["base"]
     image_name = distro_base_section["image"]  # should always exist
+    if args.distribution_image:
+        print()
+        print_notice(f"Overriding distribution's container image '{image_name}' with the one "
+                     f"provided on the command-line: {args.distribution_image}")
+        print()
+        image_name = args.distribution_image
     shared_root_dirs = distro_base_section["shared_root_dirs"]  # should always exist
     secondary_groups = distro_base_section["secondary_groups"]  # should always exist
     return image_name, shared_root_dirs, secondary_groups, distro_config
@@ -576,6 +618,12 @@ def process_base_section(base_section: SectionProxy, profile: PathName, conf: St
         elif key == "dbus":
             if _get_boolean(val):
                 enable_dbus(docker_args, base_section.getboolean("dbus_sys", fallback=False), env)
+        elif key == "ssh_agent":
+            if _get_boolean(val):
+                enable_ssh_agent(docker_args, env)
+        elif key == "gpg_agent":
+            if _get_boolean(val):
+                enable_gpg_agent(docker_args, env)
         elif key == "dri":
             dri = _get_boolean(val)
         elif key == "nvidia":
@@ -598,6 +646,9 @@ def process_base_section(base_section: SectionProxy, profile: PathName, conf: St
                         (re.match("^--log-opt=path=(.*)/.*$", path) for path in docker_args) if mt]
             for log_dir in log_dirs:
                 os.makedirs(log_dir, mode=Consts.default_directory_mode(), exist_ok=True)
+        elif key == "devices":
+            if val:
+                add_multi_opt(docker_args, "device", val)
         elif key not in ("name", "dbus_sys", "includes"):
             raise NotSupportedError(f"Unknown key '{key}' in the [base] of {profile} "
                                     "or its includes")
@@ -654,21 +705,51 @@ def enable_dbus(docker_args: list[str], sys_enable: bool, env: Environ) -> None:
                        to the user dbus message bus
     :param env: an instance of the current :class:`Environ`
     """
-    def replace_target_dir(src: str) -> str:
-        return src.replace(f"{env.xdg_rt_dir}/", f"{env.target_xdg_rt_dir}/")
     if dbus_session := os.environ.get("DBUS_SESSION_BUS_ADDRESS"):
         dbus_user = dbus_session[dbus_session.find("=") + 1:]
         if (dbus_opts_idx := dbus_user.find(",")) != -1:
             dbus_user = dbus_user[:dbus_opts_idx]
-        add_mount_option(docker_args, dbus_user, replace_target_dir(dbus_user))
-        add_env_option(docker_args, "DBUS_SESSION_BUS_ADDRESS", replace_target_dir(dbus_session))
+        add_mount_option(docker_args, dbus_user, _replace_xdg_rt_dir(dbus_user, env))
+        add_env_option(docker_args, "DBUS_SESSION_BUS_ADDRESS",
+                       _replace_xdg_rt_dir(dbus_session, env))
     if sys_enable:
-        dbus_sys = "/run/dbus/system_bus_socket"
-        dbus_sys2 = "/var/run/dbus/system_bus_socket"
-        if os.access(dbus_sys, os.W_OK):
-            add_mount_option(docker_args, dbus_sys, dbus_sys)
-        elif os.access(dbus_sys2, os.W_OK):
-            add_mount_option(docker_args, dbus_sys2, dbus_sys)
+        for dbus_sys in ("/run/dbus/system_bus_socket", "/var/run/dbus/system_bus_socket"):
+            if os.access(dbus_sys, os.W_OK):
+                add_mount_option(docker_args, dbus_sys, dbus_sys)
+                break
+
+
+def enable_ssh_agent(docker_args: list[str], env: Environ) -> None:
+    """
+    Append options to podman/docker arguments to share host machine's ssh agent socket
+    with the new ybox container.
+
+    :param docker_args: list of podman/docker arguments to which the options have to be appended
+    :param env: an instance of the current :class:`Environ`
+    """
+    if ssh_auth_sock := os.environ.get("SSH_AUTH_SOCK"):
+        target_ssh_auth_sock = handle_variable_mount(docker_args, env, ssh_auth_sock)
+        add_env_option(docker_args, "SSH_AUTH_SOCK", target_ssh_auth_sock)
+        add_env_option(docker_args, "SSH_AUTH_SOCK_ORIG", target_ssh_auth_sock)
+
+
+def enable_gpg_agent(docker_args: list[str], env: Environ) -> None:
+    """
+    Append options to podman/docker arguments to share host machine's gpg agent sockets
+    with the new ybox container.
+
+    :param docker_args: list of podman/docker arguments to which the options have to be appended
+    :param env: an instance of the current :class:`Environ`
+    """
+    if gpg_agent_info := os.environ.get("GPG_AGENT_INFO"):
+        target_gpg_agent_info = handle_variable_mount(docker_args, env, gpg_agent_info)
+        add_env_option(docker_args, "GPG_AGENT_INFO", target_gpg_agent_info)
+        add_env_option(docker_args, "GPG_AGENT_INFO_ORIG", target_gpg_agent_info)
+
+
+def _replace_xdg_rt_dir(src: str, env: Environ) -> str:
+    """replace host's $XDG_RUNTIME_DIR in `src` with that of container user's $XDG_RUNTIME_DIR"""
+    return src.replace(env.xdg_rt_dir + "/", env.target_xdg_rt_dir + "/")
 
 
 def add_multi_opt(docker_args: list[str], opt: str, val: Optional[str]) -> None:
@@ -681,7 +762,7 @@ def add_multi_opt(docker_args: list[str], opt: str, val: Optional[str]) -> None:
     """
     if val:
         for opt_val in val.split(","):
-            docker_args.append(f"--{opt}={opt_val}")
+            docker_args.append(f"--{opt}={opt_val.strip()}")
 
 
 def process_security_section(sec_section: SectionProxy, profile: PathName,
@@ -759,8 +840,7 @@ def process_configs_section(configs_section: SectionProxy, config_hardlinks: boo
     # this is refreshed on every container start
 
     # always recreate the directory to pick up any changes
-    if os.path.exists(conf.configs_dir):
-        shutil.rmtree(conf.configs_dir)
+    shutil.rmtree(conf.configs_dir, ignore_errors=True)
     os.makedirs(conf.configs_dir, mode=Consts.default_directory_mode(), exist_ok=True)
     if config_hardlinks:
         print_info("Creating hard links to paths specified in [configs]  ...")
@@ -777,24 +857,38 @@ def process_configs_section(configs_section: SectionProxy, config_hardlinks: boo
                 raise NotSupportedError("Incorrect value format in [configs] section for "
                                         f"'{key}'. Required: '{{src}} -> {{dest}}'")
             src_path = os.path.realpath(f_val[:split_idx].strip())
-            dest_path = f"{conf.configs_dir}/{f_val[split_idx + 2:].strip()}"
+            dest_rel_path = f_val[split_idx + 2:].strip()
+            dest_path = f"{conf.configs_dir}/{dest_rel_path}"
             if os.access(src_path, os.R_OK):
-                os.makedirs(os.path.dirname(dest_path),
-                            mode=Consts.default_directory_mode(), exist_ok=True)
+                if os.path.exists(dest_path):
+                    shutil.rmtree(dest_path, ignore_errors=True)
+                else:
+                    os.makedirs(os.path.dirname(dest_path),
+                                mode=Consts.default_directory_mode(), exist_ok=True)
                 if os.path.isdir(src_path):
                     copytree(src_path, dest_path, hardlink=config_hardlinks)
                 else:
                     if config_hardlinks:
-                        os.link(os.path.realpath(src_path), dest_path, follow_symlinks=True)
+                        try:
+                            os.link(os.path.realpath(src_path), dest_path, follow_symlinks=True)
+                        except OSError:
+                            # in case of error (likely due to cross-device link) fallback to copy
+                            shutil.copy2(src_path, dest_path, follow_symlinks=True)
                     else:
                         shutil.copy2(src_path, dest_path, follow_symlinks=True)
-                config_list_fd.write(val)
-                config_list_fd.write("\n")
+                # - if key has ":copy", then indicate creation of copies in the target
+                # - if key has ":dir", then indicate replication of directory structure with links
+                #      for individual files
+                # - else a symlink should be created
+                # handled by "replicate_config_files" function in entrypoint.sh
+                prefix = "COPY" if key.endswith(":copy") else (
+                    "LINK_DIR" if key.endswith(":dir") else "LINK")
+                config_list_fd.write(f"{prefix}:{dest_rel_path}\n")
             else:
                 print_warn(f"Skipping inaccessible configuration path '{src_path}'")
     print_info("DONE.")
     # finally mount the configs directory to corresponding directory in the target container
-    add_mount_option(docker_args, conf.configs_dir, conf.target_configs_dir, "ro")
+    add_mount_option(docker_args, conf.configs_dir, conf.target_configs_dir)
 
 
 def process_env_section(env_section: SectionProxy, docker_args: list[str]) -> None:
@@ -822,7 +916,7 @@ def process_apps_section(apps_section: SectionProxy, conf: StaticConfiguration,
     :return: dictionary of package names mapped to their list of dependencies as specified
              in the `[apps]` section
     """
-    if len(apps_section) == 0:
+    if not apps_section:
         return {}
     quiet_flag = pkgmgr[PkgMgr.QUIET_FLAG.value]
     opt_dep_flag = pkgmgr[PkgMgr.OPT_DEP_FLAG.value]
@@ -859,37 +953,78 @@ def process_apps_section(apps_section: SectionProxy, conf: StaticConfiguration,
 
 
 # The shutil.copytree(...) method does not work correctly for "symlinks=False" (or at least
-#   not like 'cp -rL' or 'cp -rlL') where it does not create the source symlinked file rather
-# only the target one in the destination directory.
-# This is a simplified version using os.walk(...) that works correctly that always has:
-#   a. follow_symlinks=True, and b. ignore_dangling_symlinks=True
-def copytree(src: str, dest: str, hardlink: bool = False) -> None:
+#   not like 'cp -aL' or 'cp -alL') where it does not create the source symlinked file rather
+# only the target one in the destination directory, and neither does it provide the option to
+# create hardlinks.
+#
+# This is a simplified version using recursive os.scandir(...) that works correctly so that the
+# copy will continue to work even if source disappears in all cases but still avoid making copies
+# for all symlinks. So it behaves like follow_symlinks=True if the symlink destination is outside
+# the "src_path" else it is False.
+def copytree(src_path: str, dest: str, hardlink: bool = False,
+             src_root: Optional[str] = None) -> None:
     """
     Copy or create hard links to a source directory tree in the given destination directory.
     Since hard links to directories are not supported, the destination will mirror the directories
     of the source while the files inside will be either copies or hard links to the source.
+    Symlinks are copied as such if the source ones point within the tree, else the target is
+    followed and copied recursively.
 
-    :param src: the source directory tree
-    :param dest: the destination directory which should exist
+    Note: this function only handles regular files and directories (and hard/symbolic links to
+    them) and will skip special files like device files, fifos etc.
+
+    :param src_path: the source directory to be copied (should have been resolved using
+                     `os.path.realpath` or `Path.resolve` if `src_root` argument is not supplied)
+    :param dest: the destination directory which should not already exist (but its parent should)
     :param hardlink: if True then create hard links to the files in the source (so it should
                        be in the same filesystem) else copy the files, defaults to False
+    :param src_root: the resolved root source directory (same as `src_path` if `None` which is
+                     assumed to have been resolved using `os.path.realpath` or `Path.resolve`)
     """
-    for src_dir, _, src_files in os.walk(src, followlinks=True):
-        # substitute 'src' prefix with 'dest'
-        dest_dir = f"{dest}{src_dir[len(src):]}"
-        os.mkdir(dest_dir, mode=stat.S_IMODE(os.stat(src_dir).st_mode))
-        for src_file in src_files:
-            src_path = f"{src_dir}/{src_file}"
-            if os.path.exists(src_path):
-                if hardlink:
-                    try:
-                        os.link(os.path.realpath(src_path), f"{dest_dir}/{src_file}",
-                                follow_symlinks=True)
+    src_root = src_root or src_path
+    src_root = src_root.rstrip("/")
+    os.mkdir(dest, mode=stat.S_IMODE(os.stat(src_path).st_mode))
+    # follow symlink if it leads to outside the "src" tree, else copy as a symlink which
+    # ensures that all destination files are always accessible regardless of source going
+    # away (for example), and also reduces the size with hardlink=False as much as possible
+    with os.scandir(src_path) as src_it:
+        for entry in src_it:
+            entry_path = ""
+            entry_st_mode = 0
+            dest_path = f"{dest}/{entry.name}"
+            try:
+                if entry.is_symlink():
+                    # check if entry is a symlink inside the tree or outside
+                    l_name = os.readlink(entry.path)
+                    if "/" not in l_name:  # shortcut check for links in the same directory
+                        os.symlink(l_name, dest_path)
                         continue
-                    except OSError:
-                        # in case of error (likely due to cross-device link) fallback to copying
-                        pass
-                shutil.copy2(src_path, f"{dest_dir}/{src_file}", follow_symlinks=True)
+                    entry_path = os.path.realpath(entry.path)
+                    if entry_path.startswith(src_root + "/"):
+                        rpath = entry_path[len(src_root) + 1:]
+                        os.symlink(("../" * rpath.count("/")) + rpath, dest_path)
+                        continue
+                    entry_st_mode = os.stat(entry_path).st_mode
+                entry_path = entry_path or entry.path
+                if stat.S_ISREG(entry_st_mode) or (entry_st_mode == 0 and entry.is_file()):
+                    if hardlink:
+                        try:
+                            os.link(entry_path, dest_path)
+                            continue
+                        except OSError:
+                            # in case of error (likely due to cross-device link) fallback to copy
+                            pass
+                    shutil.copy2(entry_path, dest_path)
+                elif stat.S_ISDIR(entry_st_mode) or (entry_st_mode == 0 and entry.is_dir()):
+                    copytree(entry_path, dest_path, hardlink,
+                             entry_path if entry_st_mode else src_root)
+                else:
+                    print_warn(f"Skipping copy/link of special file (fifo/dev/...) '{entry_path}'")
+            except OSError as err:
+                # ignore permission and related errors and continue
+                print_warn(f"Skipping copy/link of '{entry_path}' due to error: {err}")
+        # TODO: SW: check for success in all copytree's else return False, then check at caller
+        # to print a bold warning
 
 
 def setup_ybox_scripts(conf: StaticConfiguration, distro_config: ConfigParser) -> None:
@@ -902,7 +1037,7 @@ def setup_ybox_scripts(conf: StaticConfiguration, distro_config: ConfigParser) -
                           distribution's `distro.ini`
     """
     # first create local mount directory having entrypoint and other scripts
-    if os.path.exists(conf.scripts_dir):
+    if os.path.isdir(conf.scripts_dir):
         shutil.rmtree(conf.scripts_dir)
     os.makedirs(conf.scripts_dir, exist_ok=True)
     # allow for read/execute permissions for all since non-root user needs access with docker
@@ -1030,8 +1165,8 @@ def remove_image(docker_cmd: str, image_name: str) -> None:
                 error_msg="image remove")
 
 
-def start_container(docker_full_cmd: list[str], current_user: str, shared_root: str,
-                    shared_root_dirs: str, conf: StaticConfiguration) -> None:
+def run_container(docker_full_cmd: list[str], current_user: str, shared_root: str,
+                  shared_root_dirs: str, conf: StaticConfiguration) -> None:
     """
     Create and start the final ybox container applying all the provided configuration.
     The following characteristics of the container are noteworthy:
@@ -1054,9 +1189,8 @@ def start_container(docker_full_cmd: list[str], current_user: str, shared_root:
         programs from less secure containers; the `ybox-pkg` tool provided a convenient high-level
         package manager that users should use for managing packages in the containers which will
         help in exposing packages only in designated containers
-      * systemd user service file can be generated for podman to start the container automatically
-        on user login; docker installations run a background user service in any case which starts
-        up the container without any additional setup
+      * systemd user service file is generated for podman/docker to start the container
+        automatically on user login (in absence of -S/--skip-systemd-service option)
 
     :param docker_full_cmd: the `docker`/`podman run -itd` command with all the options filled
                             in from the container profile specification as a list of string
@@ -1089,8 +1223,10 @@ def start_container(docker_full_cmd: list[str], current_user: str, shared_root:
     if conf.env.uses_podman:
         docker_full_cmd.append(f"--user={user_uid}")
         docker_full_cmd.append("--userns=keep-id")
+        docker_full_cmd.append(f"-e=USER={current_user}")
     else:
         docker_full_cmd.append("--user=0")
+        docker_full_cmd.append("-e=USER=root")
     docker_full_cmd.append(f"-e=YBOX_HOST_UID={user_uid}")
     docker_full_cmd.append(f"-e=YBOX_HOST_GID={user_gid}")
     docker_full_cmd.append(conf.box_image(bool(shared_root)))
@@ -1108,8 +1244,63 @@ def start_container(docker_full_cmd: list[str], current_user: str, shared_root:
         sys.exit(code)
 
 
-def restart_container(docker_cmd: str, conf: StaticConfiguration) -> None:
-    """restart a stopped podman/docker container"""
+def create_and_start_service(box_name: str, env: Environ, systemctl: str, sys_path: str,
+                             wait_msg: str) -> None:
+    """
+    Create, enable and start systemd service for a ybox container.
+
+    :param box_name: name of the ybox container
+    :param env: an instance of the current :class:`Environ`
+    :param systemctl: resolved path to the `systemctl` utility
+    :param sys_path: PATH used for searching system utilities
+    :param wait_msg: message to output before waiting for the service to start
+    """
+    svc_file = env.search_config_path("resources/ybox-systemd.template", only_sys_conf=True)
+    with svc_file.open("r", encoding="utf-8") as svc_fd:
+        svc_tmpl = svc_fd.read()
+    if env.uses_podman:
+        manager_name = "Podman"
+        docker_requires = ""
+    else:
+        manager_name = "Docker"
+        docker_requires = "After=docker.service\nRequires=docker.service\n"
+    systemd_dir = env.systemd_user_conf_dir()
+    ybox_svc_prefix = ybox_systemd_service_prefix(box_name)
+    ybox_svc = f"{ybox_svc_prefix}.service"
+    ybox_env = f".{ybox_svc_prefix}.env"
+    formatted_now = env.now.astimezone().strftime("%a %d %b %Y %H:%M:%S %Z")
+    # get the path of ybox-control and replace $HOME by %h to keep it generic
+    if ybox_ctrl_path := shutil.which("ybox-control"):
+        ybox_bin_dir = os.path.dirname(ybox_ctrl_path)
+        if ybox_bin_dir.startswith(env.home + "/"):
+            ybox_bin_dir = f"%h{ybox_bin_dir[len(env.home):]}"
+    else:
+        ybox_bin_dir = "%h/.local/bin"
+    svc_content = svc_tmpl.format(name=box_name, version=product_version, date=formatted_now,
+                                  manager_name=manager_name, docker_requires=docker_requires,
+                                  sys_path=sys_path, ybox_bin_dir=ybox_bin_dir, env_file=ybox_env)
+    env_content = f"""
+        SLEEP_SECS={{sleep_secs}}
+        # set the container manager to the one configured during ybox-create
+        YBOX_CONTAINER_MANAGER={env.docker_cmd}
+    """
+    os.makedirs(systemd_dir, Consts.default_directory_mode(), exist_ok=True)
+    print_color(f"Generating user systemd service '{ybox_svc}' and reloading daemon", fgcolor.cyan)
+    with open(f"{systemd_dir}/{ybox_svc}", "w", encoding="utf-8") as svc_fd:
+        svc_fd.write(svc_content)
+    with open(f"{systemd_dir}/{ybox_env}", "w", encoding="utf-8") as env_fd:
+        env_fd.write(dedent(env_content.format(sleep_secs=0)))  # don't sleep for the start below
+    run_command([systemctl, "--user", "daemon-reload"], exit_on_error=False)
+    run_command([systemctl, "--user", "enable", ybox_svc], exit_on_error=True)
+    print_info(wait_msg)
+    run_command([systemctl, "--user", "start", ybox_svc], exit_on_error=True)
+    # change SLEEP_SECS to 5 for subsequent starts
+    with open(f"{systemd_dir}/{ybox_env}", "w", encoding="utf-8") as env_fd:
+        env_fd.write(dedent(env_content.format(sleep_secs=5)))
+
+
+def start_container(docker_cmd: str, conf: StaticConfiguration) -> None:
+    """start a stopped podman/docker container"""
     if (code := int(run_command([docker_cmd, "container", "start", conf.box_name],
                                 exit_on_error=False, error_msg="container restart"))) != 0:
         print_error(f"Also check 'ybox-logs {conf.box_name}' for details")

ybox/run/destroy.py

@@ -3,11 +3,16 @@ Code for the `ybox-destroy` script that is used to destroy an active or stopped
 """
 
 import argparse
+import os
+import shutil
+import subprocess
 import sys
 
-from ybox.cmd import check_ybox_exists, run_command
+from ybox.cmd import check_ybox_exists, parser_version_check, run_command
+from ybox.config import Consts
 from ybox.env import Environ
-from ybox.print import fgcolor, print_color, print_error, print_warn
+from ybox.print import (fgcolor, print_color, print_error, print_notice,
+                        print_warn)
 from ybox.state import YboxStateManagement
 
 
@@ -31,9 +36,18 @@ def main_argv(argv: list[str]) -> None:
 
     check_ybox_exists(docker_cmd, container_name, exit_on_error=True)
     print_color(f"Stopping ybox container '{container_name}'", fg=fgcolor.cyan)
+    # check if there is a systemd service for the container
+    ybox_svc_prefix = ybox_systemd_service_prefix(container_name)
+    ybox_svc = f"{ybox_svc_prefix}.service"
+    systemctl = check_systemd_service_present(ybox_svc)
+
     # continue even if this fails since the container may already be in stopped state
-    run_command([docker_cmd, "container", "stop", container_name],
-                exit_on_error=False, error_msg=f"stopping '{container_name}'")
+    if systemctl:
+        run_command([systemctl, "--user", "stop", ybox_svc],
+                    exit_on_error=False, error_msg=f"stopping '{container_name}'")
+    else:
+        run_command([docker_cmd, "container", "stop", container_name],
+                    exit_on_error=False, error_msg=f"stopping '{container_name}'")
 
     print_warn(f"Removing ybox container '{container_name}'")
     rm_args = [docker_cmd, "container", "rm"]
@@ -42,12 +56,32 @@ def main_argv(argv: list[str]) -> None:
     rm_args.append(container_name)
     run_command(rm_args, error_msg=f"removing '{container_name}'")
 
+    # remove systemd service file and reload daemon
+    if systemctl:
+        print_color(f"Removing systemd service '{ybox_svc}' and reloading daemon", fg=fgcolor.cyan)
+        run_command([systemctl, "--user", "disable", ybox_svc], exit_on_error=False)
+        systemd_dir = env.systemd_user_conf_dir()
+        try:
+            os.unlink(f"{systemd_dir}/{ybox_svc}")
+        except OSError:
+            pass
+        try:
+            os.unlink(f"{systemd_dir}/.{ybox_svc_prefix}.env")
+        except OSError:
+            pass
+        run_command([systemctl, "--user", "daemon-reload"], exit_on_error=False)
+
+    # check and remove any dangling container references in state database
+    valid_containers = set(get_all_containers(docker_cmd))
+
     # remove the state from the database
     print_warn(f"Clearing ybox state for '{container_name}'")
     with YboxStateManagement(env) as state:
+        state.begin_transaction()
         if not state.unregister_container(container_name):
             print_error(f"No entry found for '{container_name}' in the state database")
             sys.exit(1)
+        remove_orphans_from_db(valid_containers, state)
 
 
 def parse_args(argv: list[str]) -> argparse.Namespace:
@@ -61,4 +95,55 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
     parser.add_argument("-f", "--force", action="store_true",
                         help="force destroy the container using SIGKILL if required")
     parser.add_argument("container_name", type=str, help="name of the active ybox")
+    parser_version_check(parser, argv)
     return parser.parse_args(argv)
+
+
+def ybox_systemd_service_prefix(container_name: str) -> str:
+    """systemd service name prefix for given ybox container name"""
+    return container_name if container_name.startswith("ybox-") else f"ybox-{container_name}"
+
+
+def check_systemd_service_present(user_svc: str) -> str:
+    """
+    Check if the given user systemd service is present and return the PATH of system installed
+    `systemctl` tool if true, else return empty string.
+
+    :param user_svc: name the user systemd service file
+    :return: full path of `systemctl` if installed and user systemd service is available else empty
+    """
+    if (systemctl := shutil.which("systemctl", path=os.pathsep.join(Consts.sys_bin_dirs()))) and \
+            subprocess.run([systemctl, "--user", "--quiet", "list-unit-files", user_svc],
+                           check=False, capture_output=True).returncode == 0:
+        return systemctl
+    return ""
+
+
+def get_all_containers(docker_cmd: str) -> list[str]:
+    """
+    Get all the valid containers as known to the container manager.
+
+    :param docker_cmd: the podman/docker executable to use
+    :return: list of valid container names
+    """
+    result = run_command([docker_cmd, "container", "ls", "--all", "--format={{ .Names }}"],
+                         capture_output=True, exit_on_error=False, error_msg="listing containers")
+    return [] if isinstance(result, int) else result.splitlines()
+
+
+def remove_orphans_from_db(valid_containers: set[str], state: YboxStateManagement) -> None:
+    """
+    Unregister orphan container entries from the state database. This takes the output of
+    :func:`get_all_containers` as argument and should be invoked inside `YboxStateManagement`
+    context manager (i.e. with state database as locked), while the call to `get_all_containers`
+    can be outside the lock.
+
+    :param valid_containers: set of valid container names from :func:`get_all_containers`
+    :param state: instance of `YboxStateManagement` having the state of all ybox containers
+    """
+    if not os.environ.get("YBOX_TESTING"):
+        orphans = set(state.get_containers()) - valid_containers
+        if orphans:
+            print_notice(f"Removing orphan container entries from database: {', '.join(orphans)}")
+            for orphan in orphans:
+                state.unregister_container(orphan)