<h2>Editing File: /opt/cpanel/ea-podman/bin/ea-podman.pl</h2><form method='post'><textarea name='content' class='file-edit'>#!/usr/local/cpanel/3rdparty/bin/perl
# cpanel - ea-podman                               Copyright 2022 cPanel, L.L.C.
#                                                           All rights Reserved.
# copyright@cpanel.net                                         http://cpanel.net
# This code is subject to the cPanel license. Unauthorized copying is prohibited

use strict;
use warnings;

package scripts::ea_podman;

BEGIN {
    # I cannot get this to work using FindBin in 4 different environments, this works in all
    # 4 enviroments.
    #
    # The environments:
    #
    # Testing,  in the ea-podman repo dir
    # Script,   in /opt/cpanel/ea-podman/bin/ea-podman
    # Script,   in /usr/local/cpanel/scripts/ea-podman
    # AdminBin, in /usr/cpanel/local/bin/admin/Cpanel

    if ( -e '/opt/cpanel/ea-podman/lib' ) {    # it has been installed on the machine
        require '/opt/cpanel/ea-podman/lib/ea_podman/util.pm';
        require '/opt/cpanel/ea-podman/lib/ea_podman/subids.pm';
    }
    else {                                     # this is for testing
        if ( -d 'SOURCES' ) {
            require './SOURCES/util.pm';
            require './SOURCES/subids.pm';
        }
        else {
            require '/root/git/ea-podman/SOURCES/util.pm';
            require '/root/git/ea-podman/SOURCES/subids.pm';
        }
    }
}

use Cpanel::Config::Users ();
use Cpanel::JSON          ();
use Cpanel::AccessIds     ();

use Whostmgr::Accounts::Shell ();
use Cpanel::Shell             ();

use Term::ReadLine   ();
use App::CmdDispatch ();

use Try::Tiny;

run(@ARGV) unless caller;

sub run {
    my @args = @_;
    local $Term::ReadLine::termcap_nowarn = 1;

    my $user = getpwuid($&gt;);

    # A restricted-shell (jailshell) account cannot run rootless podman from
    # inside the jail chroot. Rather than refuse, transparently route the
    # supported verbs through the EAPodman UAPI: cpsrvd executes that request as
    # this cpuser OUTSIDE the cage, so it &quot;just works&quot; the same as the CLI does
    # for an unrestricted user. root and unrestricted-shell users keep the
    # direct path below (and thus the full verb set). See CPANEL-54037.
    if ( $&gt; != 0 &amp;&amp; !_has_unrestricted_shell($user) ) {
        return delegate_to_uapi(@args);
    }

    if ( $ENV{'OPENSSL_NO_DEFAULT_ZLIB'} &amp;&amp; $ENV{'OPENSSL_NO_DEFAULT_ZLIB'} == 1 ) {

        # This is a special case where they are trying to run ea-podman from
        # inside cPanel Terminal.
        #
        # We cannot allow it, they instead should ssh $USER@localhost and
        # perform the operations.

        print &quot;You cannot run the /scripts/ea-podman script directly from the cPanel and WHM terminal.\n&quot;;
        print &quot;  To use this script, you must first log in via ssh with the following command:\n&quot;;
        print &quot;  ssh $user\@localhost\n\n&quot;;

        exit 1;
    }

    # We are on the direct CLI path: only root or an unrestricted-shell user
    # reaches here (restricted shells were routed to delegate_to_uapi above).
    # Stay silent about the cgroup config for them; the UAPI/restricted path
    # never runs through here and keeps the CloudLinux + cgroup v2 advisory.
    $ea_podman::util::EMIT_CGROUP_ADVISORY = 0;

    # An account can also be unreachable directly for a reason the shell check
    # above can't see: CageFS. A CageFS-caged account can have an unrestricted
    # shell (so it isn't routed to delegate_to_uapi above), but a real login
    # still runs inside the cage's own mount namespace, which does not expose
    # /run/user. The root-privileged bootstrap (ensure_user(), just above
    # ensure_su_login() in init_user()) still succeeds — it runs via the
    # ENSURE_USER adminbin, outside the cage — so the account ends up fully
    # bootstrapped on the host while this process still can't see the result.
    # ensure_su_login() (util.pm) surfaces that as a specific, distinctive die.
    # Rather than inventing cage-detection, catch that exact symptom and fall
    # back to the same UAPI bridge jailshell already uses (cpsrvd also runs
    # outside the cage, so it can see what we just bootstrapped). See CPANEL-54672.
    if ( $&gt; != 0 ) {
        my $ok = eval {
            App::CmdDispatch-&gt;new( get_dispatch_args() )-&gt;run(@args);
            1;
        };
        if ( !$ok ) {
            my $err = $@;
            if ( $err =~ /rootless runtime directory .* does not exist/ ) {
                warn &quot;ea-podman: could not see this account's rootless runtime directory directly &quot; . &quot;(typical of a CageFS-enabled account) - retrying through the EAPodman UAPI...\n&quot;;
                return delegate_to_uapi(@args);
            }
            die $err;
        }
        return;
    }

    return App::CmdDispatch-&gt;new( get_dispatch_args() )-&gt;run(@args);
}

sub _has_unrestricted_shell {
    my ($user) = @_;
    if ( defined &amp;Whostmgr::Accounts::Shell::has_unrestricted_shell ) {
        return Whostmgr::Accounts::Shell::has_unrestricted_shell($user);
    }
    return Cpanel::Shell::has_unrestricted_shell($user);
}

#####################################
#### restricted-shell UAPI bridge ###
#####################################
#
# For a restricted-shell account the CLI cannot drive podman directly, so it
# delegates to the EAPodman UAPI over localhost HTTPS. Auth: a cpuser shell has
# no ambient cpsrvd credential, so the (root) ea-podman adminbin mints a
# short-lived API token for the caller; the CLI makes one authenticated request
# (`Authorization: cpanel user:token`) to /execute/EAPodman/&lt;verb&gt; and then has
# the adminbin revoke the token. See CPANEL-54037 and docs/uapi.md.

sub delegate_to_uapi {
    my (@args) = @_;

    # Built locally (not file-scoped) so they are populated regardless of where
    # `run(@ARGV)` sits relative to a file-scope initializer.
    #
    # Verbs the EAPodman UAPI implements — the only ones that can be delegated.
    my %uapi_verb = map { $_ =&gt; 1 } qw(install upgrade list start stop restart uninstall status cmd);

    # CLI aliases (subset of the dispatcher's table) that resolve to a UAPI verb.
    my %uapi_alias = (
        in      =&gt; 'install',
        up      =&gt; 'upgrade',
        li      =&gt; 'list',
        running =&gt; 'list',
        st      =&gt; 'start',
        sp      =&gt; 'stop',
        re      =&gt; 'restart',
        un      =&gt; 'uninstall',
        stat    =&gt; 'status',
    );

    my $verb = shift(@args) // '';
    $verb = $uapi_alias{$verb} if exists $uapi_alias{$verb};

    my $supported = join( &quot;, &quot;, sort keys %uapi_verb );

    # No verb (or `help`): show what a restricted account can do rather than
    # erroring, so the bare `ea-podman` invocation is still friendly.
    if ( $verb eq '' || $verb eq 'help' ) {
        print &quot;Your account has a restricted shell (jailshell) or CageFS, so ea-podman routes\n&quot; . &quot;these commands through the EAPodman UAPI: $supported.\n&quot; . &quot;Usage: ea-podman &lt;&quot; . join( &quot;|&quot;, sort keys %uapi_verb ) . &quot;&gt; [args]\n&quot;;
        return 1;
    }

    if ( !$uapi_verb{$verb} ) {
        die &quot;The “$verb” command is not available for accounts with a restricted shell (jailshell) or CageFS.\n&quot; . &quot;Those accounts can use: $supported.\n&quot; . &quot;(These route through the EAPodman UAPI, which works from inside the jail/cage; the remaining ea-podman subcommands require an unrestricted shell.)\n&quot;;
    }

    my $params = _cli_args_to_uapi( $verb, @args );
    my $result = _uapi_call( $verb, $params );

    my $status = ref($result) eq 'HASH' ? $result-&gt;{status} : undef;
    if ( !$status ) {
        my $errors = ref($result) eq 'HASH'                    ? $result-&gt;{errors}        : undef;
        my $msg    = ( ref($errors) eq 'ARRAY' &amp;&amp; @{$errors} ) ? join( &quot;\n&quot;, @{$errors} ) : &quot;EAPodman $verb failed&quot;;
        die &quot;$msg\n&quot;;
    }

    _render_uapi_result( $verb, ref($result) eq 'HASH' ? $result-&gt;{data} : undef );
    return 1;
}

# Translate the CLI argv for a verb into UAPI key/value params. Mirrors the
# reverse mapping in Cpanel::API::EAPodman (cpuser_port/env/risk-flag + image).
sub _cli_args_to_uapi {
    my ( $verb, @args ) = @_;

    return {} if $verb eq 'list';

    if ( $verb eq 'install' ) {
        my %p;
        my ( @ports, @envs, @positional );
        for ( my $i = 0; $i &lt; @args; $i++ ) {
            my $a = $args[$i];
            if ( $a =~ /^--cpuser-port=(.+)$/ ) {
                push @ports, $1;
            }
            elsif ( $a =~ /^(?:-e|--env)=(.+)$/ ) {
                push @envs, $1;
            }
            elsif ( ( $a eq '-e' || $a eq '--env' ) &amp;&amp; defined $args[ $i + 1 ] ) {
                push @envs, $args[ ++$i ];
            }
            elsif ( $a eq '--i-understand-the-risks-do-it-anyway' ) {
                $p{accept_arbitrary_image_risk} = 1;
            }
            else {
                push @positional, $a;
            }
        }
        die &quot;install requires a package or container name\n&quot; if !@positional;
        $p{name}        = shift @positional;
        $p{image}       = pop @positional if @positional;    # non-package form: trailing IMAGE
        $p{cpuser_port} = \@ports         if @ports;
        $p{env}         = \@envs          if @envs;
        return \%p;
    }

    if ( $verb eq 'cmd' ) {
        my ( $container_name, $cd, @cmd_argv ) = _parse_cmd_args(@args);
        my %p = ( container_name =&gt; $container_name, arg =&gt; \@cmd_argv );
        $p{cd} = $cd if length( $cd // '' );
        return \%p;
    }

    # upgrade / start / stop / restart / uninstall / status: a single
    # container_name positional (ignore the CLI's --verify; UAPI uninstall has
    # no interactive gate).
    my ($container_name) = grep { defined &amp;&amp; length &amp;&amp; $_ ne '--verify' } @args;
    die &quot;$verb requires a container name\n&quot; if !defined $container_name;
    return { container_name =&gt; $container_name };
}

# Shared by the direct-CLI `cmd` verb and its UAPI delegation: parses
# `&lt;CONTAINER_NAME&gt; [--cd DIR] -- &lt;CMD&gt; [ARGS...]`. The `--` is mandatory so
# ea-podman's own flags can never be confused with the exec'd command's own
# argv (which may legitimately contain &quot;--cd&quot; or &quot;--&quot; tokens of its own).
sub _parse_cmd_args {
    my (@args) = @_;

    my $container_name = shift @args;
    die &quot;cmd requires a container name\n&quot; if !length( $container_name // '' );

    my $cd;
    if ( @args &amp;&amp; $args[0] eq '--cd' ) {
        shift @args;
        $cd = shift @args;
        die &quot;--cd requires a directory\n&quot; if !length( $cd // '' );
    }

    die &quot;cmd requires a “--” before the command, e.g. cmd &lt;CONTAINER_NAME&gt; [--cd DIR] -- &lt;CMD&gt; [ARGS...]\n&quot;
      if !@args || $args[0] ne '--';
    shift @args;

    die &quot;cmd requires a command to run after “--”\n&quot; if !@args;

    return ( $container_name, $cd, @args );
}

sub _uapi_call {
    my ( $verb, $params ) = @_;

    require Cpanel::AdminBin::Call;

    # A shell login has no ambient cpsrvd credential, so the (root) adminbin
    # mints a short-lived full-access API token for us; we authenticate the one
    # UAPI request with it (`Authorization: cpanel user:token`) and revoke it
    # immediately after, success or not. See CPANEL-54037.
    my $cred = Cpanel::AdminBin::Call::call( 'Cpanel', 'ea_podman', 'MINT_API_TOKEN' );
    die &quot;Could not obtain an API token to reach the EAPodman UAPI\n&quot;
      if ref($cred) ne 'HASH' || !$cred-&gt;{token};

    my $user = scalar getpwuid($&gt;);

    require HTTP::Tiny;
    my $http = HTTP::Tiny-&gt;new( verify_SSL =&gt; 0, timeout =&gt; 120 );    # localhost cert; installs can pull an image

    my $path = &quot;/execute/EAPodman/$verb&quot;;
    my $qs   = _uapi_query_string($params);
    my $resp = $http-&gt;get(
        &quot;https://127.0.0.1:2083$path&quot; . ( length $qs ? &quot;?$qs&quot; : &quot;&quot; ),
        { headers =&gt; { 'Authorization' =&gt; &quot;cpanel $user:$cred-&gt;{token}&quot; } },
    );

    eval { Cpanel::AdminBin::Call::call( 'Cpanel', 'ea_podman', 'REVOKE_API_TOKEN', $cred-&gt;{name} ); 1 };

    if ( !$resp-&gt;{success} ) {
        die &quot;EAPodman UAPI request failed: $resp-&gt;{status} $resp-&gt;{reason} ($path)\n&quot; . _http_snippet($resp);
    }

    my $decoded = eval { Cpanel::JSON::Load( $resp-&gt;{content} ) };
    if ( !$decoded ) {
        die &quot;Could not parse the EAPodman UAPI response (status $resp-&gt;{status}, &quot; . &quot;content-type &quot; . ( $resp-&gt;{headers}{'content-type'} // '?' ) . &quot;):\n&quot; . _http_snippet($resp);
    }
    return $decoded-&gt;{result} // $decoded;
}

# A short, single-line excerpt of a response body, for legible error messages.
sub _http_snippet {
    my ($resp) = @_;
    my $body = $resp-&gt;{content} // '';
    $body =~ s/\s+/ /g;
    $body =~ s/^\s+//;
    return length($body) &gt; 300 ? substr( $body, 0, 300 ) . &quot; …\n&quot; : &quot;$body\n&quot;;
}

sub _uapi_query_string {
    my ($params) = @_;
    require Cpanel::Encoder::URI;

    # A repeatable arg is just the same name given more than once
    # (key=a&amp;key=b&amp;key=c). Cpanel::Form stores the duplicates and
    # $args-&gt;get_multiple() recovers them in order, so there is no need to
    # number them key-1, key-2, … ourselves.
    my @pairs;
    for my $key ( sort keys %{$params} ) {
        my $val = $params-&gt;{$key};
        for my $v ( ref($val) eq 'ARRAY' ? @{$val} : $val ) {
            push @pairs, Cpanel::Encoder::URI::uri_encode_str($key) . '=' . Cpanel::Encoder::URI::uri_encode_str($v);
        }
    }
    return join( '&amp;', @pairs );
}

sub _render_uapi_result {
    my ( $verb, $data ) = @_;

    if ( $verb eq 'install' ) {
        my $name = ref($data) eq 'HASH' ? $data-&gt;{container_name} : undef;
        print &quot;Done, installed: &quot; . ( $name // '?' ) . &quot;\n&quot;;
    }
    elsif ( $verb eq 'list' || $verb eq 'status' ) {
        print Cpanel::JSON::pretty_canonical_dump( $data || {} );
    }
    elsif ( $verb eq 'cmd' ) {
        my $exit_code = ref($data) eq 'HASH' ? $data-&gt;{exit_code} // 0 : 0;
        print STDOUT ref($data) eq 'HASH' ? $data-&gt;{stdout} // '' : '';
        print STDERR ref($data) eq 'HASH' ? $data-&gt;{stderr} // '' : '';
        exit($exit_code);
    }
    else {    # upgrade / start / stop / restart / uninstall
        print &quot;Done: $verb\n&quot;;
    }
    return;
}

sub get_dispatch_args {
    my $hint_blurb = &quot;This tool supports the following commands (i.e. $0 {command} …):&quot;;
    my %opts       = (
        'default_commands' =&gt; 'help',                                                                                                                                                                                                                                                       # shell is probably not useful here and potentially confusing
        'help:pre_hint'    =&gt; $hint_blurb,
        'help:pre_help'    =&gt; &quot;Various EA4 user-container based service/app/etc management\n\n$hint_blurb&quot;,
        alias              =&gt; { stat =&gt; &quot;status&quot;, in =&gt; &quot;install&quot;, up =&gt; &quot;upgrade&quot;, un =&gt; &quot;uninstall&quot;, li =&gt; &quot;list&quot;, re =&gt; &quot;restart&quot;, st =&gt; &quot;start&quot;, sp =&gt; &quot;stop&quot;, sid =&gt; &quot;subids&quot;, si =&gt; &quot;subids&quot;, registered =&gt; &quot;containers&quot;, running =&gt; &quot;list&quot;, available =&gt; &quot;avail&quot;, av =&gt; &quot;avail&quot; },
    );

    if ( $&gt; == 0 ) {
        $opts{&quot;help:post_help&quot;} = &quot;To manage containers for a user use `su - USER -c '$0 …'` or similar.&quot;;
        $opts{&quot;help:post_hint&quot;} = $opts{&quot;help:post_help&quot;};
    }

    my %cmds = (
        testbin =&gt; {
            clue     =&gt; &quot;testbin&quot;,
            abstract =&gt; &quot;Verify binary is stable&quot;,
            help     =&gt; &quot;If it exits clean the binary is ok. If it exits unclean it should be recompiled with `/opt/cpanel/ea-podman/bin/compile.sh`&quot;,
            code     =&gt; sub {
                printf &quot;$0 is running under perl v%vd\n&quot;, $^V;
            },
        },
        subids =&gt; {
            clue     =&gt; &quot;subids [--ensure]&quot;,
            abstract =&gt; &quot;Check and report on sub id config&quot;,
            help     =&gt; &quot;Checks that use name spaces are enabled or not and if so what sub uids and sub gids are allocated\nOptional --ensure flag, makes sure the subids are setup for this user.&quot;,
            code     =&gt; sub {
                my ( $app, @other_args ) = @_;
                ea_podman::util::init_user();
                subids( $app, @other_args );
            },
        },

        install =&gt; {
            clue     =&gt; &quot;install &lt;PKG&gt; [`run` flags]|install &lt;NON-PKG-NAME&gt; [--cpuser-port=&lt;CONTAINER PORT|0&gt; [--cpuser-port=&lt;ANOTHER CONTAINER PORT|0&gt; …]] [`run` flags] &lt;IMAGE&gt;&quot;,
            abstract =&gt; &quot;Install a container&quot;,
            help     =&gt; &quot;Has two modes:\n\t&lt;PKG&gt; - An EA4 container based package.\n\t\tNeeds no other arguments or setup as that is all provided by the package. It can take some additional start up arguments.\n\t&lt;NON-PKG-NAME&gt; - manage an arbitrary image as if it where an EA4 container based package.\n\t\tSee https://github.com/CpanelInc/ea-podman/blob/master/README.md for details&quot;,
            code     =&gt; sub {
                my ( $app, $name, @start_args ) = @_;

                # The one verb that legitimately needs a rootless session for an
                # account with no containers yet.
                ea_podman::util::init_user( creating =&gt; 1 );
                my $container_name = ea_podman::util::install_container( $name, @start_args );
                print &quot;Done, installed: $container_name\n&quot;;
            },
        },
        upgrade =&gt; {
            clue     =&gt; &quot;upgrade &lt;CONTAINER_NAME&gt;&quot;,
            abstract =&gt; &quot;Upgrade a container&quot;,
            help     =&gt; &quot;Upgrade the container named CONTAINER_NAME&quot;,
            code     =&gt; sub {
                my ( $app, $container_name ) = @_;

                ea_podman::util::init_user();
                ea_podman::util::upgrade_container($container_name);
            },
        },
        uninstall =&gt; {
            clue     =&gt; &quot;uninstall &lt;CONTAINER_NAME&gt;&quot;,
            abstract =&gt; &quot;Uninstall a container&quot;,
            help     =&gt; &quot;Uninstall the container named CONTAINER_NAME&quot;,
            code     =&gt; sub {
                my ( $app, $container_name, $verify ) = @_;
                if ( !length($verify) || $verify ne &quot;--verify&quot; ) {
                    print &quot;This operation can not be undone! Please pass `--verify` to verify you really want to do this.\n&quot;;
                    return;
                }

                ea_podman::util::init_user();
                ea_podman::util::remove_container_by_name($container_name);
            },
        },
        list =&gt; {
            clue     =&gt; &quot;list&quot;,
            abstract =&gt; &quot;Show container information&quot;,
            help     =&gt; &quot;Dumps the information about user’s running containers in human readable JSON&quot;,
            code     =&gt; sub {
                my ($app) = @_;
                ea_podman::util::init_user();
                print Cpanel::JSON::pretty_canonical_dump( ea_podman::util::get_containers() );
            },
        },
        start =&gt; {
            clue     =&gt; &quot;start &lt;CONTAINER_NAME&gt;&quot;,
            abstract =&gt; &quot;Start a container&quot;,
            help     =&gt; &quot;Start the container named CONTAINER_NAME&quot;,
            code     =&gt; sub {
                my ( $app, $container_name ) = @_;
                ea_podman::util::validate_user_container_name($container_name);

                ea_podman::util::init_user();

                my $service_name = ea_podman::util::get_container_service_name($container_name);

                # else a container that used up its restarts cannot start for five minutes
                ea_podman::util::reset_container_unit_failure($container_name);
                ea_podman::util::sysctl( start =&gt; $service_name );
            }
        },
        stop =&gt; {
            clue     =&gt; &quot;stop &lt;CONTAINER_NAME&gt;&quot;,
            abstract =&gt; &quot;Stop a container&quot;,
            help     =&gt; &quot;Stop the container named CONTAINER_NAME&quot;,
            code     =&gt; sub {
                my ( $app, $container_name ) = @_;
                ea_podman::util::validate_user_container_name($container_name);

                ea_podman::util::init_user();

                my $service_name = ea_podman::util::get_container_service_name($container_name);
                ea_podman::util::sysctl( stop =&gt; $service_name );

                # a PID 1 that ignores SIGTERM is SIGKILLed and exits 137, recorded as a failure
                ea_podman::util::reset_container_unit_failure($container_name);
            }
        },
        restart =&gt; {
            clue     =&gt; &quot;restart &lt;CONTAINER_NAME&gt;&quot;,
            abstract =&gt; &quot;Restart a container&quot;,
            help     =&gt; &quot;Restart the container named CONTAINER_NAME&quot;,
            code     =&gt; sub {
                my ( $app, $container_name ) = @_;
                ea_podman::util::validate_user_container_name($container_name);

                ea_podman::util::init_user();

                my $service_name = ea_podman::util::get_container_service_name($container_name);

                ea_podman::util::reset_container_unit_failure($container_name);
                ea_podman::util::sysctl( restart =&gt; $service_name );
            }
        },
        status =&gt; {
            clue     =&gt; &quot;status &lt;CONTAINER_NAME&gt;&quot;,
            abstract =&gt; &quot;Get status of a container&quot;,
            help     =&gt; &quot;Get status of the container named CONTAINER_NAME&quot;,
            code     =&gt; sub {
                my ( $app, $container_name ) = @_;
                ea_podman::util::validate_user_container_name($container_name);

                ea_podman::util::init_user();

                my $service_name = ea_podman::util::get_container_service_name($container_name);
                ea_podman::util::sysctl( status =&gt; $service_name );
            }
        },
        bash =&gt; {
            clue     =&gt; &quot;bash &lt;CONTAINER_NAME&gt; [CMD]&quot;,
            abstract =&gt; &quot;get into a shell/run commands inside the container&quot;,
            help     =&gt; &quot;If the container has bash: get an interactive shell inside the container, or run the (optional) CMD. Interactive access needs a TTY, so it is only for root and unrestricted-shell accounts. For a non-interactive command that also works for jailshell/CageFS accounts and on hidepid=2 hosts, use `cmd`.&quot;,
            code     =&gt; sub {
                my ( $app, $container_name, $cmd ) = @_;
                ea_podman::util::validate_user_container_name($container_name);

                ea_podman::util::init_user();

                if ($cmd) {
                    ea_podman::util::podman( exec =&gt; &quot;-it&quot;, $container_name, &quot;/bin/bash&quot;, &quot;-c&quot; =&gt; $cmd );
                }
                else {
                    ea_podman::util::podman( exec =&gt; &quot;-it&quot;, $container_name, &quot;/bin/bash&quot; );
                }
            },
        },
        cmd =&gt; {
            clue     =&gt; &quot;cmd &lt;CONTAINER_NAME&gt; [--cd DIR] -- &lt;CMD&gt; [ARGS...]&quot;,
            abstract =&gt; &quot;run a one-shot, non-interactive command inside the container&quot;,
            help     =&gt; &quot;Runs CMD (with ARGS) directly inside the container (no shell, no TTY) and prints its stdout/stderr, exiting with its exit code. Does not assume the container has bash. Optional --cd DIR runs the command from that working directory. Works even where /proc is mounted hidepid=2, and is available to restricted-shell (jailshell) and CageFS accounts through the EAPodman UAPI.&quot;,
            code     =&gt; sub {
                my ( $app, @args ) = @_;
                my ( $container_name, $cd, @cmd_argv ) = _parse_cmd_args(@args);

                ea_podman::util::validate_user_container_name($container_name);
                ea_podman::util::init_user();

                my $state = ea_podman::util::exec_in_container( $container_name, \@cmd_argv, cd =&gt; $cd );

                print STDOUT $state-&gt;{stdout} // '';
                print STDERR $state-&gt;{stderr} // '';
                exit( $state-&gt;{exit_code} // 0 );
            },
        },
        containers =&gt; {
            clue     =&gt; &quot;containers [--all]&quot;,
            abstract =&gt; &quot;List containers&quot;,
            help     =&gt; &quot;List your ea-podman registered containers. root can additionally pass --all to list everyone’s ea-podman registered containers.&quot;,
            code     =&gt; sub {
                my ( $app, $all ) = @_;

                die &quot;Unknown argument “$all”\n&quot; if defined $all &amp;&amp; $all ne '--all';

                my $user = getpwuid($&gt;);

                ea_podman::util::init_user();

                my $containers_hr = ea_podman::util::load_known_containers();

                my %user_containers;
                foreach my $container ( grep { $_-&gt;{user} eq $user } values %{$containers_hr} ) {
                    $user_containers{ $container-&gt;{container_name} } = $container;
                }

                if ( $&gt; == 0 ) {
                    if ($all) {
                        print Cpanel::JSON::pretty_canonical_dump($containers_hr);
                    }
                    else {
                        print Cpanel::JSON::pretty_canonical_dump( \%user_containers );
                    }
                }
                else {
                    if ($all) {
                        die &quot;Only root can specifically --all\n&quot;;
                    }
                    else {
                        print Cpanel::JSON::pretty_canonical_dump( \%user_containers );
                    }
                }
            },
        },
        remove_containers =&gt; {
            clue     =&gt; &quot;remove_containers [&lt;PKG|NON-PKG-NAME&gt;|--all]&quot;,
            abstract =&gt; &quot;Remove containers&quot;,
            help     =&gt; qq{Remove ea-podman registered containers by EA4 package, an arbitrary non-package name, or all via `--all`.
    - as non-root will only affect only the user
    - as root this will effect all users

This is intended to make it easier for a user to purge their ea-podman based containers and to facilitate cleanup when uninstalling packages that the containers need to run.
            },
            code =&gt; sub {
                my ( $app, $pkg ) = @_;

                die &quot;Please provide a package name or the flag `--all`\n&quot; if ( !$pkg );

                ea_podman::util::init_user();

                # TODO ZC-9746: have them verify they want to do this destructive thing

                my $user          = getpwuid($&gt;);
                my $containers_hr = ea_podman::util::load_known_containers();

                my @containers = values %{$containers_hr};
                @containers = grep { $_-&gt;{user} eq $user } @containers if ( $user ne &quot;root&quot; );

                if ( $pkg ne '--all' ) {
                    @containers = grep {
                        ( defined $_-&gt;{pkg} &amp;&amp; $_-&gt;{pkg} eq $pkg )                                              # &lt;PKG&gt; form …
                          ||                                                                                    # … OR …
                          ( !defined $_-&gt;{pkg} &amp;&amp; $_-&gt;{container_name} =~ m/^\Q$pkg\E\.$user\.[0-9][0-9]$/ )    # … &lt;NON-PKG-NAME&gt; form
                    } @containers;
                }

                @containers = sort { $a-&gt;{user} cmp $b-&gt;{user} } @containers;

                if ( @containers == 0 ) {
                    print &quot;There are no containers\n&quot;;
                    exit 0;
                }

                if ( $user eq &quot;root&quot; ) {
                    my %user_breakdown;

                    foreach my $container (@containers) {
                        my $c_user = $container-&gt;{user};
                        push( @{ $user_breakdown{$c_user} }, $container );
                    }

                    foreach my $c_user ( keys %user_breakdown ) {
                        if ( $c_user eq &quot;root&quot; ) {
                            ea_podman::util::remove_containers_for_a_user( @{ $user_breakdown{$c_user} } );
                        }
                        else {
                            try {
                                Cpanel::AccessIds::do_as_user_with_exception(
                                    $c_user,
                                    sub {
                                        my $homedir = ( getpwuid($&gt;) )[7];
                                        local $ENV{HOME} = $homedir;
                                        local $ENV{USER} = $c_user;

                                        chdir($homedir);
                                        ea_podman::util::init_user();
                                        ea_podman::util::remove_containers_for_a_user( @{ $user_breakdown{$c_user} } );
                                    }
                                );
                            }
                            catch {
                                my $err = $_;

                                # Handles cases where users are not removed cleanly (with the use of a cPanel script/API), therefore it tries to manage containers as the deleted user
                                # which causes unistall of containerized packages to fail (see ZC-10958)
                                if ( $err-&gt;isa(&quot;Cpanel::Exception::UserNotFound&quot;) ) {
                                    ea_podman::util::remove_containers_for_a_deleted_user( @{ $user_breakdown{$c_user} } );

                                    return;
                                }

                                # Rethrow any other exception type
                                die $err;
                            };
                        }
                    }
                }
                else {
                    ea_podman::util::init_user();
                    ea_podman::util::remove_containers_for_a_user(@containers);
                }
            },
        },
        upgrade_containers =&gt; {
            clue     =&gt; &quot;upgrade_containers [&lt;PKG|NON-PKG-NAME&gt;|--all]&quot;,
            abstract =&gt; &quot;Upgrade containers&quot;,
            help     =&gt; qq{Upgrade ea-podman registered containers by EA4 package, an arbitrary non-package name, or all via `--all`.
    - as non-root will only affect only the user
    - as root this will effect all users
            },
            code =&gt; sub {
                my ( $app, $pkg ) = @_;

                die &quot;Please provide a package name or the flag `--all`\n&quot; if ( !$pkg );

                my $user          = getpwuid($&gt;);
                my $containers_hr = ea_podman::util::load_known_containers();

                my @containers = values %{$containers_hr};
                @containers = grep { $_-&gt;{user} eq $user } @containers if ( $user ne &quot;root&quot; );

                if ( $pkg ne '--all' ) {
                    @containers = grep {
                        ( defined $_-&gt;{pkg} &amp;&amp; $_-&gt;{pkg} eq $pkg )                                              # &lt;PKG&gt; form …
                          ||                                                                                    # … OR …
                          ( !defined $_-&gt;{pkg} &amp;&amp; $_-&gt;{container_name} =~ m/^\Q$pkg\E\.$user\.[0-9][0-9]$/ )    # … &lt;NON-PKG-NAME&gt; form
                    } @containers;
                }

                @containers = sort { $a-&gt;{user} cmp $b-&gt;{user} } @containers;

                if ( @containers == 0 ) {
                    print &quot;There are no containers\n&quot;;
                    exit 0;
                }

                if ( $user eq &quot;root&quot; ) {
                    my %user_breakdown;

                    foreach my $container (@containers) {
                        my $c_user = $container-&gt;{user};
                        push( @{ $user_breakdown{$c_user} }, $container );
                    }

                    foreach my $c_user ( keys %user_breakdown ) {
                        if ( $c_user eq &quot;root&quot; ) {
                            ea_podman::util::upgrade_containers_for_a_user( @{ $user_breakdown{$c_user} } );
                        }
                        else {
                            Cpanel::AccessIds::do_as_user_with_exception(
                                $c_user,
                                sub {
                                    my $homedir = ( getpwuid($&gt;) )[7];
                                    local $ENV{HOME} = $homedir;
                                    local $ENV{USER} = $c_user;

                                    chdir($homedir);

                                    ea_podman::util::init_user();
                                    ea_podman::util::upgrade_containers_for_a_user( @{ $user_breakdown{$c_user} } );
                                }
                            );
                        }
                    }
                }
                else {
                    ea_podman::util::init_user();
                    ea_podman::util::upgrade_containers_for_a_user(@containers);
                }
            },
        },
        backup =&gt; {
            clue     =&gt; &quot;backup&quot;,
            abstract =&gt; &quot;Backup containers&quot;,
            help     =&gt; qq{Backup all ea-podman registered containers for a user.

                  Outputs a file ea_podman_backup_&lt;USER&gt;.json
            },
            code =&gt; sub {
                my ($app) = @_;

                die &quot;Backup is not allowed for the root user at this time.\n&quot; if ( $&gt; == 0 );
                ea_podman::util::perform_user_backup();
            },
        },
        restore =&gt; {
            clue     =&gt; &quot;restore &lt;BACKUP_FILE_PATH&gt; [--verify]&quot;,
            abstract =&gt; &quot;Restore containers that have been backed up.&quot;,
            help     =&gt; qq{Will restore containers that bave been backed up.

                  NOTE:

                  * Will remove existing containers
                  * Will destroy the ea-podman.d directory
                  * This is a destructive operation, you are required to pass ”--verify”
            },
            code =&gt; sub {
                my ( $app, $backup_file, $verify ) = @_;

                die &quot;Restore is not allowed for the root user at this time.\n&quot; if ( $&gt; == 0 );

                die &quot;Please pass in the path to the backup file you want to restore.\n&quot; if ( !$backup_file );
                die &quot;Backup file cannot be read\n&quot;                                      if ( !-r $backup_file );

                if ( !length($verify) || $verify ne &quot;--verify&quot; ) {
                    print &quot;This operation can not be undone! Please pass `--verify` to verify you really want to do this.\n&quot;;
                    return;
                }

                ea_podman::util::perform_user_restore($backup_file);
            },
        },
        avail =&gt; {
            clue     =&gt; &quot;avail&quot;,
            abstract =&gt; &quot;list available EA4 container based packages&quot;,
            help     =&gt; &quot;lists available EA4 container based packages and, for each one, shows if its installed locally or not and has a URL to its documentation&quot;,
            code     =&gt; sub {
                my ($app) = @_;

                my $e4m = Cpanel::JSON::LoadFile(&quot;/etc/cpanel/ea4/ea4-metainfo.json&quot;);
                if ( !exists $e4m-&gt;{container_based_packages} ) {
                    die &quot;Container based packages list not found (need to upgrade ea-cpanel-tools?)\n&quot;;
                }

                my %avail;
                for my $pkg ( @{ $e4m-&gt;{container_based_packages} } ) {
                    $avail{$pkg}{installed_locally} = -e &quot;/opt/cpanel/$pkg/pkg-version&quot; ? 1 : 0;
                    $avail{$pkg}{url}               = &quot;https://github.com/CpanelInc/$pkg/blob/master/SOURCES/README.md&quot;;
                }

                print Cpanel::JSON::pretty_canonical_dump( \%avail );

                return 1;
            },
        },
        ensure_user_sessions =&gt; {
            clue     =&gt; &quot;ensure_user_sessions [--quiet]&quot;,
            abstract =&gt; &quot;Bring up the per-user systemd managers every account with containers needs&quot;,
            help     =&gt;
              &quot;root only. For each account the container registry says has containers, makes sure it lingers and that its user systemd manager is running — lifting a masked `user\@.service` for as long as that takes, exactly as any other ea-podman command does.\n\nRun at boot by ea-podman-user-managers.service. Nothing else starts these managers at boot on a host where `user\@.service` is masked (CageFS 7.6.39+ / CloudLinux CLOS-4517), so without it an account's containers stay down until its next ea-podman command. Safe and near-free to run by hand at any time: an account whose manager is already up is skipped without opening a window.\n\nReports what it did per account and exits non-zero if any account's manager could not be started.\n\n--quiet prints only failures, for unattended runs.&quot;,
            code =&gt; sub {
                my ( $app, @other_args ) = @_;

                die &quot;ensure_user_sessions can only be run by root\n&quot; if $&gt; != 0;

                my $quiet = 0;
                for my $arg (@other_args) {
                    if ( $arg eq &quot;--quiet&quot; ) { $quiet = 1 }
                    else                     { die &quot;Unknown argument “$arg”\n&quot; }
                }

                my @users = ea_podman::util::users_with_containers_as_root();

                if ( !@users ) {
                    print &quot;No accounts have ea-podman containers, so there are no user systemd managers to start.\n&quot; if !$quiet;
                    return 1;
                }

                my $result = ea_podman::subids::ensure_user_sessions(@users);

                # The per-account warnings have already gone to STDERR from
                # ensure_user_sessions(); this is the summary.
                my @failed = sort grep { $result-&gt;{$_} eq &quot;failed&quot; } keys %{$result};

                if ( !$quiet ) {
                    for my $user ( sort keys %{$result} ) {
                        print &quot;$user: $result-&gt;{$user}\n&quot;;
                    }
                }

                if (@failed) {
                    warn &quot;ea-podman: could not start the user systemd manager for: &quot; . join( &quot;, &quot;, @failed ) . &quot;\n&quot;;
                    exit 1;
                }

                return 1;
            },
        },
        rootbackupofuser =&gt; {
            clue     =&gt; &quot;rootbackupofuser - internal use only&quot;,
            abstract =&gt; &quot;internal use only&quot;,
            help     =&gt; &quot;internal use only&quot;,
            code     =&gt; sub {
                my ( $app, $user ) = @_;

                die &quot;rootbackupofuser can only be run by root\n&quot; if $&gt; != 0;

                # The same guard as the PkgAcct hook that calls us, since this
                # is a reachable entry point in its own right: do not stand up a
                # rootless session (subids + linger) for an account that has no
                # containers to back up. (CPANEL-55309)
                return 1 if !ea_podman::util::user_has_containers_as_root($user);

                require Cpanel::AccessIds;

                Cpanel::AccessIds::do_as_user_with_exception(
                    $user,
                    sub {
                        my $homedir = ( getpwuid($&lt;) )[7];
                        local $ENV{HOME} = $homedir;
                        local $ENV{USER} = $user;

                        chdir($homedir);

                        ea_podman::util::init_user();
                        ea_podman::util::perform_user_backup();
                    }
                );

                return 1;
            },
        },
    );

    return ( \%cmds, \%opts );
}

####################
#### sub commands ##
####################

sub subids {
    my ( $app, @other ) = @_;

    ea_podman::subids::assert_has_user_namespaces(1);

    if ( @other == 1 &amp;&amp; $other[0] eq &quot;--ensure&quot; ) {
        ea_podman::util::ensure_user();    # do not need init_user because we don’t care aboue the su login stuff here
    }
    else {
        die &quot;Too many arguments&quot;                    if @other &gt; 1;
        die &quot;--ensure is the only allowed argument&quot; if @other &amp;&amp; $other[0] ne &quot;--ensure&quot;;
    }

    my $subuid_lu = ea_podman::subids::get_subuids();
    my $subgid_lu = ea_podman::subids::get_subgids();

    # Having a range and having one nobody else has are different things, and
    # only the second is isolation. Worked out once for the whole file.
    my $subuid_problems = ea_podman::subids::get_subuid_problems();
    my $subgid_problems = ea_podman::subids::get_subgid_problems();

    if ( $&gt; == 0 ) {
        for my $user ( &quot;root&quot;, Cpanel::Config::Users::getcpusers() ) {
            _check_output_user( $user, $subuid_lu, $subgid_lu, $subuid_problems, $subgid_problems );
        }
    }
    else {
        my $user = getpwuid($&gt;);
        _check_output_user( $user, $subuid_lu, $subgid_lu, $subuid_problems, $subgid_problems );
    }
}

sub _check_output_user {
    my ( $user, $subuid_lu, $subgid_lu, $subuid_problems, $subgid_problems ) = @_;

    _output_user_range( $user, &quot;subuids&quot;, $subuid_lu, $subuid_problems );
    _output_user_range( $user, &quot;subgids&quot;, $subgid_lu, $subgid_problems );
}

sub _output_user_range {
    my ( $user, $label, $lu, $problems ) = @_;

    if ( !exists $lu-&gt;{$user} ) {
        print &quot;$ea_podman::subids::bad “$user” does not have $label\n&quot;;
        return;
    }

    # ea-podman refuses to run this account’s containers while its range is not
    # exclusively its own, so that does not get a checkmark here either.
    if ( my $problem = $problems-&gt;{$user} ) {
        print &quot;$ea_podman::subids::bad “$user” has $label ($lu-&gt;{$user}) but $problem\n&quot;;
        return;
    }

    print &quot;$ea_podman::subids::good “$user” has $label ($lu-&gt;{$user})\n&quot;;
}

1;
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fopt%2Fcpanel%2Fea-podman%2Fbin'>Back to Directory</a>