rda-python-setuid 1.0.9__py3-none-any.whl → 3.0.0__py3-none-any.whl

rda_python_setuid/install.py

@@ -15,17 +15,23 @@
 #   pywrapper-install
 #
 #   # 1. Compile and install pywrapper (run once per environment):
-#   pywrapper-install -c [-u gdexdata] [-e $ENVHOME]
+#   pywrapper-install -c [-n gdexdata] [-e $ENVHOME]
 #
 #   # 2. Create pgstart_USER entry so USER can run commands as themselves:
-#   pywrapper-install -p [-u zji] [-e $ENVHOME]
+#   pywrapper-install -p [-n zji] [-e $ENVHOME]
 #
 #   # 3. Create a symlink so a program runs as CommonUser via pywrapper (setuid):
-#   pywrapper-install -l myprog [-u gdexdata] [-e $ENVHOME]
+#   pywrapper-install -l myprog [-n gdexdata] [-e $ENVHOME]
+#
+#   # 3b. Auto-link all discovered setuid_* entries that are not yet linked:
+#   pywrapper-install -l all [-e $ENVHOME]
 #
 #   # 4. Simple install: symlink PROGRAM -> setuid_PROGRAM (no setuid, runs as current user):
 #   pywrapper-install -l myprog -s [-e $ENVHOME]
 #
+#   # 5. Update existing installation (recompile and reinstall all setuid binaries):
+#   pywrapper-install -u [-n gdexdata] [-e $ENVHOME]
+#
 # Convention for wrapped programs:
 #   The target package must register its connector entry point with a setuid_ prefix:
 #      [project.scripts]
@@ -77,7 +83,7 @@ def main():
       help="Path to the venv root directory containing bin/ (default: parent of the current Python executable's bin/ dir)"
    )
    parser.add_argument(
-      '-u', '--user', default=None,
+      '-n', '--username', default=None,
       help="User name to own the setuid binary (default: current login user for -p/--pgstart, gdexdata otherwise)"
    )
    parser.add_argument(
@@ -95,57 +101,105 @@ def main():
    )
    group.add_argument(
       '-l', '--link', metavar='PROGRAM',
-      help="Create symlink PROGRAM -> pywrapper for running a fixed program as CommonUser (Mode 1)"
+      help="Create symlink PROGRAM -> pywrapper for running a fixed program as CommonUser (Mode 1); use 'all' to auto-link every setuid_* entry not yet linked"
+   )
+   group.add_argument(
+      '-u', '--update', action='store_true',
+      help="Update an existing installation: recompile pywrapper and reinstall all pgstart_USER setuid binaries"
    )
    args = parser.parse_args()
 
-   if not (args.compile or args.pgstart or args.link):
+   if not (args.compile or args.pgstart or args.link or args.update):
       show_usage()
 
-   if args.user is None and not args.simple:
+   if args.username is None and not args.simple:
       import pwd
       if args.pgstart:
-         args.user = pwd.getpwuid(os.getuid()).pw_name
+         args.username = pwd.getpwuid(os.getuid()).pw_name
       else:
-         args.user = 'gdexdata'
+         args.username = 'gdexdata'
 
    bindir = os.path.join(args.envhome, 'bin') if args.envhome else get_bindir()
    pywrapper = os.path.join(bindir, 'pywrapper')
 
    if args.link:
-      target = os.path.join(bindir, args.link)
-      script = os.path.join(bindir, 'setuid_{}'.format(args.link))
-      if not os.path.exists(script):
-         print("Error: {} not found. Install the package that provides it first.".format(script))
-         sys.exit(1)
-      if args.simple:
-         # Simple install: symlink PROGRAM -> setuid_PROGRAM, no setuid, runs as current user.
-         if os.path.lexists(target):
-            print("Already exists: {}".format(target))
-         else:
-            os.symlink(script, target)
-            print("Created: {} -> setuid_{}".format(target, args.link))
+      # For appname -> pywrapper links, run `ln -s` via pgstart_<commonuser> so
+      # the resulting symlink is owned by the common user (pywrapper owner).
+      pgstart_common = None
+      if not args.simple and os.path.exists(pywrapper):
+         import pwd
+         common_user = pwd.getpwuid(os.stat(pywrapper).st_uid).pw_name
+         pgstart_common = os.path.join(bindir, 'pgstart_' + common_user)
+         if not os.path.exists(pgstart_common):
+            print("Error: {} not found. Run pywrapper-install --pgstart --username {} first.".format(pgstart_common, common_user))
+            sys.exit(1)
+
+      if args.link.lower() == 'all':
+         # Discover all setuid_* entries in bindir and link any that are missing
+         appnames = sorted(
+            f[len('setuid_'):] for f in os.listdir(bindir) if f.startswith('setuid_')
+         )
+         if not appnames:
+            print("No setuid_* entries found in {}".format(bindir))
+         for appname in appnames:
+            target = os.path.join(bindir, appname)
+            script = os.path.join(bindir, 'setuid_' + appname)
+            if args.simple:
+               if os.path.lexists(target):
+                  print("Already exists: {}".format(target))
+               else:
+                  os.symlink(script, target)
+                  print("Created: {} -> setuid_{}".format(target, appname))
+            else:
+               if os.path.lexists(target):
+                  print("Already exists: {}".format(target))
+               else:
+                  run([pgstart_common, 'ln', '-s', pywrapper, target])
+                  print("Created: {} -> pywrapper".format(target))
       else:
-         # Mode 1: symlink PROGRAM -> pywrapper. setuid_PROGRAM is left with its
-         # default ownership/permissions so it can be loaded and executed normally.
-         if os.path.lexists(target):
-            print("Already exists: {}".format(target))
+         target = os.path.join(bindir, args.link)
+         script = os.path.join(bindir, 'setuid_{}'.format(args.link))
+         if not os.path.exists(script):
+            print("Error: {} not found. Install the package that provides it first.".format(script))
+            sys.exit(1)
+         if args.simple:
+            # Simple install: symlink PROGRAM -> setuid_PROGRAM, no setuid, runs as current user.
+            if os.path.lexists(target):
+               print("Already exists: {}".format(target))
+            else:
+               os.symlink(script, target)
+               print("Created: {} -> setuid_{}".format(target, args.link))
          else:
-            os.symlink(pywrapper, target)
-            print("Created: {} -> pywrapper".format(target))
+            # Mode 1: symlink PROGRAM -> pywrapper. setuid_PROGRAM is left with its
+            # default ownership/permissions so it can be loaded and executed normally.
+            if os.path.lexists(target):
+               print("Already exists: {}".format(target))
+            else:
+               run([pgstart_common, 'ln', '-s', pywrapper, target])
+               print("Created: {} -> pywrapper".format(target))
 
    elif args.pgstart:
-      # Mode 2: copy pywrapper to pgstart_USER with setuid owned by USER
+      # Mode 2: create pgstart_USER with setuid owned by USER.
+      # When USER already owns pywrapper (i.e. the common user), pywrapper is
+      # already setuid owned by USER, so a symlink is sufficient; otherwise
+      # copy pywrapper and chmod 4750 as USER.
       if not os.path.exists(pywrapper):
-         print("Error: {} not found. Run pywrapper-install --user COMMONUSER first.".format(pywrapper))
+         print("Error: {} not found. Run pywrapper-install --compile --username COMMONUSER first.".format(pywrapper))
          sys.exit(1)
-      target = os.path.join(bindir, 'pgstart_{}'.format(args.user))
+      target = os.path.join(bindir, 'pgstart_{}'.format(args.username))
       import pwd
-      curuser = pwd.getpwuid(os.getuid()).pw_name
-      sudo_prefix = [] if curuser == args.user else ['sudo', '-u', args.user]
-      run(sudo_prefix + ['cp', pywrapper, target])
-      run(sudo_prefix + ['chmod', '4750', target])
-      print("Installed: {} (setuid, owned by {})".format(target, args.user))
+      pywrapper_owner = pwd.getpwuid(os.stat(pywrapper).st_uid).pw_name
+      if args.username == pywrapper_owner:
+         if os.path.lexists(target):
+            os.remove(target)
+         os.symlink(pywrapper, target)
+         print("Linked: {} -> pywrapper (setuid, owned by {})".format(target, args.username))
+      else:
+         curuser = pwd.getpwuid(os.getuid()).pw_name
+         sudo_prefix = [] if curuser == args.username else ['sudo', '-u', args.username]
+         run(sudo_prefix + ['cp', pywrapper, target])
+         run(sudo_prefix + ['chmod', '4750', target])
+         print("Installed: {} (setuid, owned by {})".format(target, args.username))
 
    elif args.compile:
       # Compile pywrapper.c and install pywrapper with setuid
@@ -153,9 +207,80 @@ def main():
       src_dest = os.path.join(bindir, 'pywrapper.c')
       shutil.copy(src, src_dest)
       print("Copied: {}".format(src_dest))
-      run(['sudo', '-u', args.user, 'gcc', '-o', pywrapper, src_dest])
-      run(['sudo', '-u', args.user, 'chmod', '4750', pywrapper])
-      print("Installed: {} (setuid, owned by {})".format(pywrapper, args.user))
+      run(['sudo', '-u', args.username, 'gcc', '-o', pywrapper, src_dest])
+      run(['sudo', '-u', args.username, 'chmod', '4750', pywrapper])
+      print("Installed: {} (setuid, owned by {})".format(pywrapper, args.username))
+
+   elif args.update:
+      # Update an existing installation: recompile pywrapper and reinstall all setuid binaries
+      pgstart_files = sorted(f for f in os.listdir(bindir) if f.startswith('pgstart_'))
+      if not pgstart_files:
+         print("Error: No pgstart_* binaries found in {}".format(bindir))
+         sys.exit(1)
+      if not os.path.exists(pywrapper):
+         print("Error: {} not found.".format(pywrapper))
+         sys.exit(1)
+
+      gdexuser = args.username
+      pgstart_gdexdata = os.path.join(bindir, 'pgstart_' + gdexuser)
+      if not os.path.exists(pgstart_gdexdata):
+         print("Error: {} not found.".format(pgstart_gdexdata))
+         sys.exit(1)
+
+      update_tmp = os.path.join(bindir, 'update_tmp')
+      os.makedirs(update_tmp, exist_ok=True)
+      print("Created: {}".format(update_tmp))
+
+      # Symlink pgstart.py into update_tmp so pywrapper instances running from
+      # update_tmp can find it via the fpath/pgstart.py fallback lookup.
+      bindir_pgstart_py = os.path.join(bindir, 'pgstart.py')
+      update_pgstart_py = os.path.join(update_tmp, 'pgstart.py')
+      if not os.path.lexists(update_pgstart_py):
+         os.symlink(bindir_pgstart_py, update_pgstart_py)
+         print("Linked: {} -> {}".format(update_pgstart_py, bindir_pgstart_py))
+
+      # Copy each non-gdex pgstart_USERNAME into update_tmp using itself, then chmod 4750
+      for fname in pgstart_files:
+         username = fname[len('pgstart_'):]
+         if username == gdexuser:
+            continue
+         src_pgstart = os.path.join(bindir, fname)
+         dst_pgstart = os.path.join(update_tmp, fname)
+         run([src_pgstart, 'cp', src_pgstart, update_tmp + '/'])
+         run([src_pgstart, 'chmod', '4750', dst_pgstart])
+
+      # Copy pywrapper into update_tmp as gdexdata, chmod, then hardlink as pgstart_gdexdata
+      update_pywrapper = os.path.join(update_tmp, 'pywrapper')
+      update_pgstart_gdexdata = os.path.join(update_tmp, 'pgstart_' + gdexuser)
+      run([pgstart_gdexdata, 'cp', pywrapper, update_tmp + '/'])
+      run([pgstart_gdexdata, 'chmod', '4750', update_pywrapper])
+      run([pgstart_gdexdata, 'ln', update_pywrapper, update_pgstart_gdexdata])
+
+      # Compile new pywrapper using update_tmp/pgstart_gdexdata
+      src = get_c_source()
+      src_dest = os.path.join(bindir, 'pywrapper.c')
+      shutil.copy(src, src_dest)
+      print("Copied: {}".format(src_dest))
+      run([update_pgstart_gdexdata, 'gcc', '-o', pywrapper, src_dest])
+      run([update_pgstart_gdexdata, 'chmod', '4750', pywrapper])
+      print("Compiled: {} (setuid, owned by {})".format(pywrapper, gdexuser))
+
+      # Recreate each pgstart_* in bindir using the corresponding update_tmp/pgstart_*
+      for fname in sorted(f for f in os.listdir(update_tmp) if f.startswith('pgstart_')):
+         username = fname[len('pgstart_'):]
+         update_pgstart = os.path.join(update_tmp, fname)
+         target = os.path.join(bindir, fname)
+         if username == gdexuser:
+            run([update_pgstart_gdexdata, 'ln', '-sf', pywrapper, target])
+            print("Linked: {} -> pywrapper (setuid, owned by {})".format(target, gdexuser))
+         else:
+            run([update_pgstart, 'cp', pywrapper, target])
+            run([update_pgstart, 'chmod', '4750', target])
+            print("Updated: {} (setuid, owned by {})".format(target, username))
+
+      # Clean up the temporary working directory
+      shutil.rmtree(update_tmp)
+      print("Removed: {}".format(update_tmp))
 
 
 if __name__ == '__main__': main()

rda_python_setuid/install.usg

@@ -2,16 +2,17 @@
  that execute Python scripts as a common or effective user via the setuid mechanism.
  Must be run inside the target Python virtual environment.
 
- Usage: pywrapper-install [-u|--user USER] [-e|--envhome ENVHOME]
+ Usage: pywrapper-install [-n|--username USERNAME] [-e|--envhome ENVHOME]
                           ( -c|--compile
                           | -p|--pgstart
-                          | -l|--link PROGRAM [-s|--simple] )
+                          | -l|--link PROGRAM|all [-s|--simple]
+                          | -u|--update )
 
  Run pywrapper-install with no arguments to display this user guide.  Exactly
- one of -c/--compile, -p/--pgstart, or -l/--link must be given to perform an
- action.
+ one of -c/--compile, -p/--pgstart, -l/--link, or -u/--update must be given
+ to perform an action.
 
-      - Option -u or --user USER
+      - Option -n or --username USERNAME
           The user name to own the setuid binary.  For Mode 1 (CommonUser program),
           this is the common user (e.g. gdexdata).  For Mode 2 (pgstart), this is
           the specialist user (e.g. zji).  Defaults to 'gdexdata' unless -p/--pgstart
@@ -31,20 +32,34 @@
 
       - Option -p or --pgstart
           Mode 2: copy the compiled pywrapper binary to pgstart_USER (owned by USER,
-          chmod 4750).  Allows USER to run arbitrary commands as themselves via the
-          setuid wrapper.  Cannot be combined with -c/--compile or -l/--link.
-
-      - Option -l or --link PROGRAM
+          chmod 4750).  Allows USER (any login user in the same group as the
+          common user PGLOG['COMMONUSER']) to run arbitrary commands as themselves
+          via the setuid wrapper.  Two paths for setting up pgstart_USER:
+            (a) if PGLOG['ADMINUSER'] (default zji) can 'sudo -u USER', the admin
+                runs 'pywrapper-install -p -n USER' on behalf of USER; or
+            (b) USER runs the same command themselves (no sudo required).
+          Cannot be combined with -c/--compile or -l/--link.
+
+      - Option -l or --link PROGRAM|all
           Mode 1: create a symlink PROGRAM -> pywrapper in the bin/ directory so
           that running PROGRAM invokes the setuid wrapper, which then execs
           setuid_PROGRAM as CommonUser.  setuid_PROGRAM keeps its default
           ownership and permissions.  Cannot be combined with -c/--compile or
           -p/--pgstart.
+          Use 'all' instead of a program name to scan bin/ for every setuid_*
+          entry and add any missing PROGRAM -> pywrapper symlinks in one pass.
+
+      - Option -u or --update
+          Update an existing installation.  Discovers all pgstart_* and pywrapper
+          binaries already present in bin/, saves them to a temporary update_tmp/
+          subdirectory, recompiles pywrapper using update_tmp/pgstart_COMMONUSER, and
+          reinstalls every pgstart_* binary from update_tmp.  Use -n/--username to
+          specify the gdex common user (default: gdexdata).
 
       - Option -s or --simple (use with -l/--link)
           Simple install: create a symlink PROGRAM -> setuid_PROGRAM directly,
           skipping the setuid mechanism entirely.  The program runs as the current
-          user with no privilege change.  -u/--user is not required with this option.
+          user with no privilege change.  -n/--username is not required with this option.
           Useful for users who do not need or cannot set up the setuid wrapper.
 
  Convention for wrapped programs:
@@ -111,10 +126,14 @@
          pywrapper-install -c
 
    3. Wire up each program as a setuid entry:
-         pywrapper-install -l dsarch
+         pywrapper-install -l dsarch        # one program
+         pywrapper-install -l all           # or all setuid_* entries at once
 
-   4. Optionally, allow a specialist to run commands as themselves:
-         pywrapper-install -p
+   4. Optionally, install a pgstart_<loginname> binary so <loginname> (any
+      user in the same group as PGLOG['COMMONUSER']) can run commands as
+      themselves.  Either PGLOG['ADMINUSER'] (default zji, if it has
+      'sudo -u <loginname>'), or <loginname> directly, runs:
+         pywrapper-install -p -n <loginname>
 
    Option B - Simple install (no sudo required, runs as current user):
 
@@ -122,7 +141,8 @@
          pip install rda_python_dsarch
 
    2. Create a direct symlink to the connector script:
-         pywrapper-install -l dsarch -s
+         pywrapper-install -l dsarch -s     # one program
+         pywrapper-install -l all -s        # or all setuid_* entries at once
 
  Examples:
 
@@ -135,8 +155,18 @@
    3. Wire up dsarch to run as gdexdata via pywrapper:
          pywrapper-install -l dsarch
 
-   4. Allow specialist zji to run commands as themselves via pgstart:
-         pywrapper-install -p -u zji
+   4. Wire up all setuid_* entries at once:
+         pywrapper-install -l all
 
-   5. Simple install of dsarch for a user who does not need setuid:
+   5. Install pgstart_zji so login user zji can run commands as themselves
+      via pgstart (run by ADMINUSER with 'sudo -u zji' available, or by zji):
+         pywrapper-install -p -n zji
+
+   6. Update an existing installation (recompile and reinstall all setuid binaries):
+         pywrapper-install -u
+
+   7. Simple install of dsarch for a user who does not need setuid:
          pywrapper-install -l dsarch -s
+
+   8. Simple install of all setuid_* entries at once:
+         pywrapper-install -l all -s

rda_python_setuid/pgstart.py

@@ -40,7 +40,7 @@ def main():
    pglog = PgLOG()
    permit = False
    pglog.PGLOG['LOGFILE'] = "pgstart.log"
-   aname = PgLOG.get_command()
+   aname = pglog.get_command()
    bckgrd = False
    workdir = None
    argv = sys.argv[1:]
@@ -49,7 +49,7 @@ def main():
    euid = pglog.PGLOG['EUID']
    ruser = pwd.getpwuid(ruid).pw_name
    euser = pwd.getpwuid(euid).pw_name
-   if ruser == euser or ruser == pglog.PGLOG['GDEXUSER'] or euser == pglog.PGLOG['GDEXUSER']: permit = True
+   if ruser in [pglog.PGLOG['ADMINUSER'], euser, pglog.PGLOG['COMMONUSER']] or euser == pglog.PGLOG['COMMONUSER']: permit = True
    pglog.set_suid(euid)
 
    while argv:
@@ -69,7 +69,7 @@ def main():
       print("* Your Login Name is {}({}) & Effective User Name is {}({}).".format(ruser, ruid, euser, euid))
       print("* Pass a command or options -(bg|fg|cwd|env|inc|plg) to run '{}'.".format(aname))
       if not permit:
-         print("* You must be '{}' or '{}' to execute a command as user '{}'.".format(euser, pglog.PGLOG['GDEXUSER'], euser))
+         print("* You must be '{}' or '{}' to execute a command as user '{}'.".format(euser, pglog.PGLOG['COMMONUSER'], euser))
       print("********************************************************************")
       sys.exit(0)
 

rda_python_setuid/pywrapper.py

@@ -32,6 +32,8 @@ def main():
       -plg  -- print PGLOG variables and exit
    """
    pglog = PgLOG()
+   from rda_python_setuid.setup_guide import show_setup_guide
+   show_setup_guide(pglog, 'rda_python_setuid', ['pywrapper'])
    pglog.set_suid(pglog.PGLOG['EUID'])
    inc = True
    print("********************************************************************")

rda_python_setuid/setuid_setup.usg

@@ -0,0 +1,75 @@
+
+ {PKGNAME} - Setuid Setup Guide
+ ===============================
+
+ The following programs must run as the common user 'gdexdata' via the
+ rda_python_setuid mechanism:
+
+   {APPNAMES}
+
+ rda_python_setuid is installed automatically as a dependency.
+
+ If you are seeing this message after running a setuid_ connector script
+ directly, the setuid wrapper has not been set up yet.  Follow the steps
+ below.
+
+ Run 'pywrapper-install' with no arguments for the full pywrapper user guide.
+
+ Environment Setup
+ -----------------
+
+   Option A - Python venv (DECS machines):
+      python3 -m venv $ENVHOME          # e.g. /glade/u/home/gdexdata/gdexmsenv
+      source $ENVHOME/bin/activate
+
+   Option B - Conda (DAV/Casper):
+      conda create --prefix $ENVHOME python=3.12   # e.g. /glade/work/gdexdata/conda-envs/pg-gdex
+      conda activate $ENVHOME
+
+ Full Setuid Setup (requires sudo access to gdexdata)
+ ----------------------------------------------------
+
+   # 1. Install the target package (pulls in rda_python_setuid automatically):
+   pip install {PKGNAME}
+
+   # 2. Compile the pywrapper C binary (once per environment):
+   pywrapper-install -c|--compile -n|--username gdexdata
+
+   # 3. Wire up each program as a setuid entry (specify name or use 'all'):
+   pywrapper-install -l|--link <program>
+   pywrapper-install -l|--link all     # auto-link every setuid_* entry not yet linked
+
+   # 4. Optionally, install a pgstart_<loginname> binary so <loginname>
+   #    (any user in the same group as PGLOG['COMMONUSER']) can run commands
+   #    as themselves via the setuid wrapper.  Same command in both cases,
+   #    only the invoker differs:
+   #
+   #    4a. If PGLOG['ADMINUSER'] (default zji) can 'sudo -u <loginname>',
+   #        the admin sets it up on the user's behalf:
+   pywrapper-install -p|--pgstart -n|--username <loginname>
+   #
+   #    4b. Otherwise <loginname> runs the same command themselves (no sudo
+   #        from ADMINUSER required, since they already are <loginname>):
+   pywrapper-install -p|--pgstart -n|--username <loginname>
+
+ Update Existing Installation (no sudo required)
+ -----------------------------------------------
+
+   When the package is upgraded and a new pywrapper.c is bundled, use
+   -u/--update to recompile and reinstall all setuid binaries without
+   needing sudo.  The existing pgstart_* binaries in bin/ are used to
+   perform the privileged operations:
+
+   pywrapper-install -u|--update [-n|--username gdexdata] [-e|--envhome $ENVHOME]
+
+ Simple Install (no sudo required, runs as current user)
+ -------------------------------------------------------
+
+   Users who do not need the setuid mechanism can create direct symlinks
+   from <name> to setuid_<name>:
+
+   pywrapper-install -l|--link <program> -s|--simple
+   pywrapper-install -l|--link all -s|--simple    # or link all setuid_* entries at once
+
+   The programs run as the current user with no privilege change.
+

rda_python_setuid/setup_guide.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+#
+##################################################################################
+#
+#     Title: setup_guide
+#    Author: Zaihua Ji, zji@ucar.edu
+#      Date: 2026-05-21
+#   Purpose: Shared setuid setup guide displayed when a package's setuid_* entry
+#            point is invoked directly (i.e. before pywrapper symlinks are
+#            configured).  Each package's setuid entry point calls
+#            show_setup_guide(pkgname, appnames) with its own metadata.
+#
+#    Github: https://github.com/NCAR/rda-python-setuid.git
+#
+##################################################################################
+
+import os
+import sys
+
+
+def show_setup_guide(obj, pkgname, appnames):
+   """Display the setuid setup guide if invoked directly, otherwise return.
+
+   When a package's setuid entry point (e.g. ``setuid_dsarch``) is invoked
+   directly before pywrapper symlinks are set up, ``obj.get_command()``
+   returns the literal ``setuid_<appname>`` (no prefix stripping, since
+   euid is the real user, not COMMONUSER).  In that case this function reads
+   ``setuid_setup.usg`` bundled with rda_python_setuid, substitutes
+   ``{PKGNAME}`` and ``{APPNAMES}``, prints the guide, and exits.
+
+   When invoked via the pywrapper symlink (euid = COMMONUSER), the
+   ``setuid_`` prefix is stripped by ``get_command()``, the membership
+   check fails, and this function returns silently so the program runs
+   normally.
+
+   Args:
+      obj: An instance derived from PgLOG (e.g. DsArch, RdaCp); provides
+         ``get_command()`` with access to ``self.PGLOG['COMMONUSER']``.
+      pkgname: Distribution name (e.g. ``rda_python_dsarch``).
+      appnames: List of program names provided by the package that need
+         setuid (e.g. ``['dsarch']`` or ``['rdacp', 'rdakill', 'rdamod']``).
+   """
+   if obj.get_command(sys.argv[0]) not in ['setuid_' + a for a in appnames]:
+      return
+   usgfile = os.path.join(os.path.dirname(__file__), 'setuid_setup.usg')
+   with open(usgfile) as f:
+      text = f.read()
+   text = text.replace('{PKGNAME}', pkgname)
+   text = text.replace('{APPNAMES}', '   '.join(appnames))
+   print(text)
+   sys.exit(0)

{rda_python_setuid-1.0.9.dist-info → rda_python_setuid-3.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rda_python_setuid
-Version: 1.0.9
+Version: 3.0.0
 Summary: RDA Python Package to setuid for program executions as an effective or common user
 Author-email: Zaihua Ji <zji@ucar.edu>
 Project-URL: Homepage, https://github.com/NCAR/rda-python-setuid
@@ -27,8 +27,10 @@ Two modes are supported:
 
 - **Mode 1 (CommonUser program):** a symlink `dsarch -> pywrapper` runs `setuid_dsarch`
   as the common user.
-- **Mode 2 (pgstart specialist):** a copy `pgstart_zji` runs any command as specialist
-  `zji` via `pgstart.py`, restricted to authorized users.
+- **Mode 2 (pgstart specialist):** a copy `pgstart_<loginname>` (e.g. `pgstart_zji`)
+  runs any command as `<loginname>` via `pgstart.py`.  `<loginname>` can be any
+  user that belongs to the same group as `PGLOG['COMMONUSER']`.  Execution is
+  restricted to authorized callers (see `pgstart.py` below).
 
 Two Python entry points are packaged alongside the C wrapper:
 
@@ -41,10 +43,12 @@ Two Python entry points are packaged alongside the C wrapper:
   `sys.path`, and `PGLOG` dictionary respectively — handy for verifying the
   setuid environment before wiring up a real program.
 
-- **`pgstart.py`** — the Mode 2 launcher invoked through a `pgstart_<USER>`
+- **`pgstart.py`** — the Mode 2 launcher invoked through a `pgstart_<loginname>`
   copy of `pywrapper`.  Reads the real/effective UIDs from `PGLOG`, then
-  permits execution only if the real user matches the effective user or the
-  shared GDEX common user (`PGLOG['GDEXUSER']`); unauthorized callers receive
+  permits execution only if the real user is in
+  `[PGLOG['ADMINUSER'], euser, PGLOG['COMMONUSER']]`
+  (i.e. the admin specialist `PGLOG['ADMINUSER']` — default `zji` — the
+  effective user themselves, or the shared common user); unauthorized callers receive
   an informational message and exit.  After authorization it parses leading
   flag tokens — `-bg` (background via `subprocess.Popen`), `-fg` (explicit
   foreground, default), `-cwd <dir>` (chdir before exec), and the same
@@ -78,30 +82,84 @@ automatically.  `pywrapper-install -l/--link` creates the symlink
 `dsarch -> pywrapper`; running `dsarch` goes through the setuid wrapper, which
 execs `setuid_dsarch` as CommonUser.
 
+The `main()` of each wrapped program (e.g. `rda_python_dsarch/dsarch.py`) must
+also call `show_setup_guide()` at the top of `main()`, passing an instance of
+the program's class along with the package name and list of setuid program
+names:
+
+```python
+def main():
+   from rda_python_setuid.setup_guide import show_setup_guide
+   object = DsArch()
+   show_setup_guide(object, 'rda_python_dsarch', ['dsarch'])
+   ...
+```
+
+When `setuid_dsarch` is invoked directly (before pywrapper symlinks are set
+up, so euid ≠ CommonUser), `show_setup_guide()` prints the shared setuid setup
+guide and exits.  When invoked via the `dsarch -> pywrapper` symlink (euid =
+CommonUser), `get_command()` strips the `setuid_` prefix, the check inside
+`show_setup_guide()` fails, and the program runs normally.
+
 ## Environment setup
 
+Create a Python environment first; package installs in the next section run
+inside whichever environment you activate here.
+
 ### Option A — Python venv (DECS machines)
 
 ```bash
 python3 -m venv $ENVHOME          # e.g. /glade/u/home/gdexdata/gdexmsenv
 source $ENVHOME/bin/activate
-pip install rda_python_setuid rda_python_dsarch ...
 ```
 
 ### Option B — Conda (DAV/Casper)
 
 ```bash
-conda create -n pg-gdex python=3.10
-conda activate pg-gdex
-pip install rda_python_setuid rda_python_dsarch ...
+conda create --prefix $ENVHOME python=3.12   # e.g. /glade/work/gdexdata/conda-envs/pg-gdex
+conda activate $ENVHOME
 ```
 
-The conda environment is typically at `/glade/work/gdexdata/conda-envs/pg-gdex`.
+## Installing rda-python-setuid
 
-## Installation
+Pick whichever install mode fits your workflow.  All four pull in the
+transitive dependency (`rda_python_common`) automatically.  Once installed,
+the `pywrapper-install` CLI is available for the setuid wiring steps below.
 
-After setting up the environment and installing packages, run `pywrapper-install`
-with no arguments to display the full user guide:
+For local development, clone this repo alongside your project and install it
+in editable mode so that changes are picked up without re-installing:
+
+```bash
+git clone https://github.com/NCAR/rda-python-setuid.git
+cd rda-python-setuid
+pip install -e .
+```
+
+To test a specific branch (e.g. an in-progress feature or fix branch), pass
+`-b/--branch` to `git clone`:
+
+```bash
+git clone -b <branch-name> https://github.com/NCAR/rda-python-setuid.git
+cd rda-python-setuid
+pip install -e .
+```
+
+For a regular (non-editable) install from a checkout:
+
+```bash
+pip install /path/to/rda-python-setuid
+```
+
+For a production install on a system that uses the published distribution:
+
+```bash
+pip install rda_python_setuid
+```
+
+## Setuid wrapper setup
+
+With `rda_python_setuid` installed in the active environment, run
+`pywrapper-install` with no arguments to display the full user guide:
 
 ```bash
 pywrapper-install
@@ -116,11 +174,32 @@ pip install rda_python_dsarch
 # 2. Compile pywrapper C binary (once per environment):
 pywrapper-install -c|--compile
 
-# 3. Wire up each program as a setuid entry:
+# 3. Wire up each program as a setuid entry (specify name or use 'all'):
 pywrapper-install -l|--link dsarch
+pywrapper-install -l|--link all           # auto-link every setuid_* entry not yet linked
+
+# 4. Optionally, install a pgstart_<loginname> binary so <loginname> (any user
+#    in the same group as PGLOG['COMMONUSER']) can run commands as themselves
+#    via the setuid wrapper.  Same command in both cases — only the invoker
+#    differs:
+#
+#    4a. If PGLOG['ADMINUSER'] (default zji) can `sudo -u <loginname>`, the
+#        admin sets it up on the user's behalf:
+pywrapper-install -p|--pgstart -n|--username <loginname>
+#
+#    4b. Otherwise <loginname> runs the same command themselves (no sudo
+#        from ADMINUSER required, since they already are <loginname>):
+pywrapper-install -p|--pgstart -n|--username <loginname>
+```
 
-# 4. Optionally, allow a specialist to run commands as themselves:
-pywrapper-install -p|--pgstart -u|--user zji
+### Update an existing installation (no sudo required)
+
+When the package is upgraded and a new `pywrapper.c` is bundled, use `-u/--update`
+to recompile and reinstall all setuid binaries without needing `sudo`.  The existing
+`pgstart_*` binaries in `bin/` are used to perform the privileged operations:
+
+```bash
+pywrapper-install -u|--update [-n|--username gdexdata] [-e|--envhome $ENVHOME]
 ```
 
 ### Simple install (no sudo required, runs as current user)
@@ -131,6 +210,7 @@ direct symlink from `dsarch` to `setuid_dsarch`:
 ```bash
 pip install rda_python_dsarch
 pywrapper-install -l|--link dsarch -s|--simple
+pywrapper-install -l|--link all -s|--simple   # or link all setuid_* entries at once
 ```
 
 ## Runtime flow

rda_python_setuid-3.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+rda_python_setuid/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+rda_python_setuid/install.py,sha256=IguehVEMgY08-mNZcDPL4sMX5_XF5sb71qwkzE-wTqU,12422
+rda_python_setuid/install.usg,sha256=CEeRuUO4_3dzwlIk0uEbDl-6HtYNGm16pltBvNfJqkw,7397
+rda_python_setuid/pgstart.py,sha256=tYCOTJedqE5Lc6hUD2tyQparsOK9VGJ2alHHLNWqF20,3968
+rda_python_setuid/pywrapper.c,sha256=Dp9EOFU9IShduQ4WMeFRiiIJLQvgZHsiQlc89vJgtII,4190
+rda_python_setuid/pywrapper.py,sha256=7RHpWeyHGLP_7Vx3KJ_yy-3qYObYg_ar6meuworA0MA,3023
+rda_python_setuid/setuid_setup.usg,sha256=nJaS08GtlCQmXiy-udp6cxCFgZZJuBaZ36DicUn5Q7I,2915
+rda_python_setuid/setup_guide.py,sha256=thdTlYJwhID63G7G9NWte0qeXwH6ytQPLFbjesWodNQ,2158
+rda_python_setuid-3.0.0.dist-info/licenses/LICENSE,sha256=1dck4EAQwv8QweDWCXDx-4Or0S8YwiCstaso_H57Pno,1097
+rda_python_setuid-3.0.0.dist-info/METADATA,sha256=JTvNrLDE7D3GZV1-Rr2ElyksAB8Bv0FmSVgsazKwnR0,8184
+rda_python_setuid-3.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rda_python_setuid-3.0.0.dist-info/entry_points.txt,sha256=mWZUCa2KYzGsYVa33M7W03CY9SMsJYsywlIDF-4iMaQ,165
+rda_python_setuid-3.0.0.dist-info/top_level.txt,sha256=ONMhKLagyTBktuz5dTyipSnRC0YhomTMs8eFRjM9kHQ,18
+rda_python_setuid-3.0.0.dist-info/RECORD,,

rda_python_setuid-1.0.9.dist-info/RECORD

@@ -1,12 +0,0 @@
-rda_python_setuid/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-rda_python_setuid/install.py,sha256=0tY0zo7WRyQMm0iUi1_XYyjR8SDVU17R729ehATZNKw,6071
-rda_python_setuid/install.usg,sha256=m0tgMS_Jh9-1wxCkbbgDNVJb3MGlMSp0Ecnwc9UeQcI,5582
-rda_python_setuid/pgstart.py,sha256=qM-ntQbYfEK1VYigXbNFBDOfW9nyaezjsjyomauMTbw,3945
-rda_python_setuid/pywrapper.c,sha256=Dp9EOFU9IShduQ4WMeFRiiIJLQvgZHsiQlc89vJgtII,4190
-rda_python_setuid/pywrapper.py,sha256=pyQZfITTpxQ_lVkWc_0ZJRF_sZnq8NQdOvR5lObu6mw,2898
-rda_python_setuid-1.0.9.dist-info/licenses/LICENSE,sha256=1dck4EAQwv8QweDWCXDx-4Or0S8YwiCstaso_H57Pno,1097
-rda_python_setuid-1.0.9.dist-info/METADATA,sha256=jFM7488gCNataDKePCLkILCVPD1xZ0i_2iAOSx46piA,5027
-rda_python_setuid-1.0.9.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-rda_python_setuid-1.0.9.dist-info/entry_points.txt,sha256=mWZUCa2KYzGsYVa33M7W03CY9SMsJYsywlIDF-4iMaQ,165
-rda_python_setuid-1.0.9.dist-info/top_level.txt,sha256=ONMhKLagyTBktuz5dTyipSnRC0YhomTMs8eFRjM9kHQ,18
-rda_python_setuid-1.0.9.dist-info/RECORD,,