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

rda_python_setuid/install.py

@@ -15,24 +15,31 @@
 #   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]
 #      "setuid_dsarch" = "rda_python_dsarch.dsarch:main"
 #   pip install places setuid_dsarch in the bin dir automatically.
-#   pywrapper-install --link dsarch will chown setuid_dsarch to CommonUser and
-#   chmod 700, so users cannot run it directly and must go through the setuid wrapper.
+#   pywrapper-install --link dsarch creates the symlink dsarch -> pywrapper, so
+#   users invoking dsarch go through the setuid wrapper which execs setuid_dsarch
+#   as CommonUser.
 #   pywrapper-install --link dsarch --simple creates dsarch -> setuid_dsarch directly,
 #   skipping setuid; the program runs as the current user.
 #
@@ -76,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(
@@ -94,60 +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, then lock down setuid_PROGRAM
-         # so users cannot bypass the setuid wrapper by running it directly.
-         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))
-         # chown and chmod 700: only CommonUser can execute setuid_PROGRAM directly.
-         # pywrapper (running as CommonUser via setuid) can still execv it, but any
-         # direct invocation by other users will get "permission denied".
-         run(['sudo', '-u', args.user, 'chown', args.user, script])
-         run(['sudo', '-u', args.user, 'chmod', '700', script])
-         print("Locked: {} (chmod 700, owned by {})".format(script, args.user))
+            # 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))
-      run(['sudo', '-u', args.user, 'cp', pywrapper, target])
-      run(['sudo', '-u', args.user, 'chmod', '4750', target])
-      print("Installed: {} (setuid, owned by {})".format(target, args.user))
+      target = os.path.join(bindir, 'pgstart_{}'.format(args.username))
+      import pwd
+      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
@@ -155,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,19 +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
-          Mode 1: create a symlink PROGRAM -> pywrapper in the bin/ directory, then
-          lock down setuid_PROGRAM (chmod 700, owned by USER) so users cannot bypass
-          the setuid wrapper by running setuid_PROGRAM directly.  Cannot be combined
-          with -c/--compile or -p/--pgstart.
+          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:
@@ -66,8 +82,8 @@
          "setuid_dsarch" = "rda_python_dsarch.dsarch:main"
 
       pip install then places setuid_dsarch in the bin/ directory automatically.
-      Running pywrapper-install --link will lock it down (chmod 700) so that only
-      pywrapper (running as CommonUser via its setuid bit) can execv it.
+      Running pywrapper-install --link creates the symlink dsarch -> pywrapper;
+      pywrapper (running as CommonUser via its setuid bit) execs setuid_dsarch.
 
  Environment Setup:
 
@@ -110,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):
 
@@ -121,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:
 
@@ -134,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']: 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-3.0.0.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: rda_python_setuid
+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
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 5 - Production/Stable
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rda_python_common
+Dynamic: license-file
+
+RDA Python package, including a C code wrapper, to execute commandline applications
+via setuid for effective and common user names.
+
+## Overview
+
+`rda_python_setuid` provides a C binary (`pywrapper`) that acquires a setuid effective
+user, then `execv`s a Python entry point script.  This allows Python programs to run
+as a designated common user (e.g. `gdexdata`) without requiring `sudo` access.
+
+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_<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:
+
+- **`pywrapper.py`** — the default fallback target executed when `pywrapper.c`
+  cannot resolve a matching `setuid_<program>` entry point.  Acquires the
+  effective UID via `PgLOG.set_suid()`, prints the caller's real and effective
+  user names, and shows the `pyproject.toml` snippet plus the
+  `pywrapper-install -l <program>` command needed to wrap a new script.
+  Diagnostic flags `-env`, `-inc`, and `-plg` dump the environment variables,
+  `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_<loginname>`
+  copy of `pywrapper`.  Reads the real/effective UIDs from `PGLOG`, then
+  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
+  `-env`/`-inc`/`-plg` diagnostics as `pywrapper.py` — and then runs the
+  remaining arguments as a command (`subprocess.run`/`Popen`) under the
+  effective UID, logging a host/program/timestamp/user line to `pgstart.log`.
+
+## Dependency requirement
+
+Any Python package whose programs are to be run via the setuid mechanism must declare
+`rda_python_setuid` as a dependency in its `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+  "rda_python_setuid",
+  ...
+]
+```
+
+It must also register each wrapped program's connector entry point with a `setuid_`
+prefix:
+
+```toml
+[project.scripts]
+"setuid_dsarch" = "rda_python_dsarch.dsarch:main"
+```
+
+`pip install` then places `setuid_dsarch` in the environment's `bin/` directory
+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
+```
+
+### Option B — Conda (DAV/Casper)
+
+```bash
+conda create --prefix $ENVHOME python=3.12   # e.g. /glade/work/gdexdata/conda-envs/pg-gdex
+conda activate $ENVHOME
+```
+
+## Installing rda-python-setuid
+
+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.
+
+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
+```
+
+### Full setuid setup (requires sudo access to CommonUser)
+
+```bash
+# 1. Install the target package (pulls in rda_python_setuid automatically):
+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 (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>
+```
+
+### 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)
+
+Users who do not need the setuid mechanism can skip steps 2–4 and create a
+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
+
+```
+user runs:  dsarch [args]
+              |  (symlink -> pywrapper, setuid bit -> EUID=gdexdata)
+pywrapper.c:  execv(bin/setuid_dsarch, args)
+setuid_dsarch: calls dsarch:main() as gdexdata
+```
+
+## Github
+
+<https://github.com/NCAR/rda-python-setuid>

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.8.dist-info/METADATA

@@ -1,147 +0,0 @@
-Metadata-Version: 2.4
-Name: rda_python_setuid
-Version: 1.0.8
-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
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 5 - Production/Stable
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: rda_python_common
-Dynamic: license-file
-
-RDA Python package, including a C code wrapper, to execute commandline applications
-via setuid for effective and common user names.
-
-## Overview
-
-`rda_python_setuid` provides a C binary (`pywrapper`) that acquires a setuid effective
-user, then `execv`s a Python entry point script.  This allows Python programs to run
-as a designated common user (e.g. `gdexdata`) without requiring `sudo` access.
-
-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.
-
-Two Python entry points are packaged alongside the C wrapper:
-
-- **`pywrapper.py`** — the default fallback target executed when `pywrapper.c`
-  cannot resolve a matching `setuid_<program>` entry point.  Acquires the
-  effective UID via `PgLOG.set_suid()`, prints the caller's real and effective
-  user names, and shows the `pyproject.toml` snippet plus the
-  `pywrapper-install -l <program>` command needed to wrap a new script.
-  Diagnostic flags `-env`, `-inc`, and `-plg` dump the environment variables,
-  `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>`
-  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
-  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
-  `-env`/`-inc`/`-plg` diagnostics as `pywrapper.py` — and then runs the
-  remaining arguments as a command (`subprocess.run`/`Popen`) under the
-  effective UID, logging a host/program/timestamp/user line to `pgstart.log`.
-
-## Dependency requirement
-
-Any Python package whose programs are to be run via the setuid mechanism must declare
-`rda_python_setuid` as a dependency in its `pyproject.toml`:
-
-```toml
-[project]
-dependencies = [
-  "rda_python_setuid",
-  ...
-]
-```
-
-It must also register each wrapped program's connector entry point with a `setuid_`
-prefix:
-
-```toml
-[project.scripts]
-"setuid_dsarch" = "rda_python_dsarch.dsarch:main"
-```
-
-`pip install` then places `setuid_dsarch` in the environment's `bin/` directory
-automatically.  `pywrapper-install -l/--link` locks it down to `chmod 700` so users
-cannot bypass the setuid wrapper by running it directly.
-
-## Environment setup
-
-### 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 ...
-```
-
-The conda environment is typically at `/glade/work/gdexdata/conda-envs/pg-gdex`.
-
-## Installation
-
-After setting up the environment and installing packages, run `pywrapper-install`
-with no arguments to display the full user guide:
-
-```bash
-pywrapper-install
-```
-
-### Full setuid setup (requires sudo access to CommonUser)
-
-```bash
-# 1. Install the target package (pulls in rda_python_setuid automatically):
-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:
-pywrapper-install -l|--link dsarch
-
-# 4. Optionally, allow a specialist to run commands as themselves:
-pywrapper-install -p|--pgstart -u|--user zji
-```
-
-### Simple install (no sudo required, runs as current user)
-
-Users who do not need the setuid mechanism can skip steps 2–4 and create a
-direct symlink from `dsarch` to `setuid_dsarch`:
-
-```bash
-pip install rda_python_dsarch
-pywrapper-install -l|--link dsarch -s|--simple
-```
-
-## Runtime flow
-
-```
-user runs:  dsarch [args]
-              |  (symlink -> pywrapper, setuid bit -> EUID=gdexdata)
-pywrapper.c:  execv(bin/setuid_dsarch, args)
-              |  (chmod 700, only gdexdata can exec directly)
-setuid_dsarch: calls dsarch:main() as gdexdata
-```
-
-## Github
-
-<https://github.com/NCAR/rda-python-setuid>

rda_python_setuid-1.0.8.dist-info/RECORD

@@ -1,12 +0,0 @@
-rda_python_setuid/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-rda_python_setuid/install.py,sha256=-YoqQ9OTguOwVaWGOkVEQgzZMxfpHIyG4MEM_oRA8oE,6379
-rda_python_setuid/install.usg,sha256=V2sbJo5hTB4hWKGZClAHBojm7wg1B1cQRZN7NdvTEHo,5543
-rda_python_setuid/pgstart.py,sha256=dzYzuc2ce60RNx7FBxVhUgHYwlVnbiZcCrxVQ6MvZZ4,3909
-rda_python_setuid/pywrapper.c,sha256=Dp9EOFU9IShduQ4WMeFRiiIJLQvgZHsiQlc89vJgtII,4190
-rda_python_setuid/pywrapper.py,sha256=pyQZfITTpxQ_lVkWc_0ZJRF_sZnq8NQdOvR5lObu6mw,2898
-rda_python_setuid-1.0.8.dist-info/licenses/LICENSE,sha256=1dck4EAQwv8QweDWCXDx-4Or0S8YwiCstaso_H57Pno,1097
-rda_python_setuid-1.0.8.dist-info/METADATA,sha256=sxD3iWI8gQ0iHRxYJdN853asC8dlvKP1yMae1aYOJJQ,5048
-rda_python_setuid-1.0.8.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-rda_python_setuid-1.0.8.dist-info/entry_points.txt,sha256=mWZUCa2KYzGsYVa33M7W03CY9SMsJYsywlIDF-4iMaQ,165
-rda_python_setuid-1.0.8.dist-info/top_level.txt,sha256=ONMhKLagyTBktuz5dTyipSnRC0YhomTMs8eFRjM9kHQ,18
-rda_python_setuid-1.0.8.dist-info/RECORD,,