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

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,25 +6,30 @@ 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)
@@ -33,24 +38,38 @@ def start_container(docker_cmd: str, container_name: str):
             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,31 @@ 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 main_argv(argv: list[str]) -> None:
     """
     Main entrypoint of `ybox-control` that takes a list of arguments which are usually the
@@ -73,19 +117,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 +128,42 @@ 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("--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)
+
+    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")

ybox/run/create.py

@@ -18,13 +18,16 @@ 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
 from ybox.run.graphics import (add_env_option, add_mount_option, enable_dri,
                                enable_nvidia, enable_wayland, enable_x11)
 from ybox.run.pkg import parse_args as pkg_parse_args
@@ -181,19 +184,24 @@ 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 args.systemd_service and (sys_path := os.pathsep.join(Consts.sys_bin_dirs())) and (
+            systemctl := shutil.which("systemctl", path=sys_path)):
+        create_and_start_service(box_name, env, systemctl, sys_path, wait_msg)
+    else:
+        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 +209,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 +268,9 @@ 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", "--systemd-service", action="store_true",
+                        help="create/overwrite user systemd service file for the container in "
+                             "~/.config/systemd/user and enable it by default")
     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 +279,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 +305,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 +388,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 +516,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
@@ -759,7 +790,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):
+    if os.path.isdir(conf.configs_dir):
         shutil.rmtree(conf.configs_dir)
     os.makedirs(conf.configs_dir, mode=Consts.default_directory_mode(), exist_ok=True)
     if config_hardlinks:
@@ -777,19 +808,36 @@ 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):
+                    if os.path.isdir(dest_path):
+                        shutil.rmtree(dest_path)
+                    else:
+                        os.unlink(dest_path)
+                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.")
@@ -822,7 +870,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 +907,73 @@ 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
+    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 resolved source directory (using `os.path.realpath` or `Path.resolve`)
     :param dest: the destination directory which should exist
     :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`)
     """
-    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
+    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) and entry_path[len(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}")
 
 
 def setup_ybox_scripts(conf: StaticConfiguration, distro_config: ConfigParser) -> None:
@@ -902,7 +986,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 +1114,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 +1138,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 can be generated for podman/docker to start the container
+        automatically on user login when -S/--systemd-service option has been provided
 
     :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 +1172,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 +1193,61 @@ 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()
+    pid_file = ""
+    if env.uses_podman:
+        manager_name = "Podman"
+        docker_requires = ""
+        res = run_command([env.docker_cmd, "container", "inspect", "--format={{.ConmonPidFile}}",
+                           box_name], capture_output=True, exit_on_error=False)
+        if isinstance(res, str):
+            pid_file = f"PIDFile={res}"
+    else:
+        manager_name = "Docker"
+        docker_requires = "After=docker.service\nRequires=docker.service\n"
+    systemd_dir = f"{env.home}/.config/systemd/user"
+    ybox_svc = f"ybox-{box_name}.service"
+    ybox_env = f"{systemd_dir}/.ybox-{box_name}.env"
+    formatted_now = env.now.astimezone().strftime("%a %d %b %Y %H:%M:%S %Z")
+    svc_content = svc_tmpl.format(name=box_name, version=product_version, date=formatted_now,
+                                  manager_name=manager_name, docker_requires=docker_requires,
+                                  env_file=ybox_env, pid_file=pid_file)
+    env_content = f"""
+        PATH={sys_path}:{env.home}/.local/bin
+        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(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 7 for subsequent starts
+    with open(ybox_env, "w", encoding="utf-8") as env_fd:
+        env_fd.write(dedent(env_content.format(sleep_secs=7)))
+
+
+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")