HCoop Git - hcoop/zz_old/ikiwiki/blob - MemberManual/RunningUnattendedCommands.mdwn

   1 #pragma section-numbers off
   2
   3 This is the chapter of the MemberManual that describes how to periodically run unattended commands using cron.
   4
   5 [[TableOfContents]]
   6
   7 = Introduction =
   8
   9 All users' home directories in HCoop setup are located on AFS partitions. The use of AFS implies the use of Kerberos. In essence, your Kerberos (and AFS) "identity" is completely unrelated to your Unix username. While you do automatically obtain Kerberos and AFS identity (so-called "tokens") when you log-in to HCoop machines over ssh, be aware that Unix and Kerberos/AFS login are two separate things. That's why the scripts you run unattended cannot write (or read) files because, without extra steps taken, they do not have any useful identity or access privileges to partitions where all the relevant data is residing.
  10
  11 So, in general, when you want to access AFS space (that means any file in your home directory), you first need to authenticate with Kerberos to obtain a valid TGT ("Ticket-granting ticket"). As the name implies, the TG Ticket is then used in automatically obtaining futher tickets for access to specific services (such as to ssh, ftp, bugzilla, members portal or AFS on any of the servers in the HCoop administration "realm").
  12
  13 = The AFS "Login" Process =
  14
  15 Following the above, here's the complete, "expanded" series of events that take place in a typical remote shell session:
  16
  17  1. You log in by providing your Unix username and password
  18  1. You authenticate to Kerberos and obtain the TGT by running '''kinit'''. (Verify with '''klist -5''').
  19  1. You use the TGT to obtain AFS "token" by running '''aklog'''. (Verify with '''tokens''').
  20  1. You access files in the AFS space. Actual access privileges are determined by the combination of the token you are holding and the access control lists (ACLs) set on a directory. (List access rules with '''fs la DIRECTORY''').
  21
  22 == Interactive SSH  process ==
  23
  24 Our SSH service is configured in such a way that your password is, in fact, the secret Kerberos key. So when you log in over SSH, steps 1 to 3 above are performed for you automatically and you can use AFS right away.
  25
  26 == Non-interactive (Unattended) Processes ==
  27
  28 When a script is started in your Unix name by Cron, At or any other delayed/controlled-execution facility, no Kerberos ticket (or AFS token) is obtained automatically. Part of the reason lies in the fact that Kerberos' security model makes it almost impossible - even for root users - to authenticate as yourself if the password is not provided. (Where in Unix we would use "sudo" to easily impersonate any user, here it is impossible).
  29
  30 So the way to obtain Kerberos ticket and AFS token from unattended processes will be explained.
  31
  32 = Ways of Obtaining AFS Tokens from Unattended Scripts =
  33
  34 As hinted before, a password '''must''' be present to obtain any Kerberos identity. However, that password may come ''either'' from an interactive terminal, or from a file. (A file that is residing outside of the AFS space, of course!).
  35
  36 Kerberos discourages exporting of actual password keys into files, so at HCoop we create '''two''' Kerberos "identities" for each user: one named USER (your Unix username) for interactive sessions, and the other named USER.daemon for unattended sessions.
  37
  38  1. Your USER principal has the password saved only in the protected Kerberos database and it is not possible to obtain its ticket without providing the password.
  39
  40  1. Your USER.daemon principal has a very long random secret assigned to it and its key exported to a file named ''/etc/keytabs/user.daemon/USER''. Your scripts will use the file ''/etc/keytabs/user.daemon/USER'' as a password in obtaining Kerberos/AFS identity "USER.daemon". In fact, all shared HCoop daemons also use that file to obtain permissions to write into your home directory (such as to deliver mail). Of course, Unix permissions and ownership on the keytab file are such that no other user can read your keytab file.
  41
  42 == Token "scope" ==
  43
  44 Kerberos and AFS introduce a concept called Process Authentication Group ("PAG").
  45
  46  * If you obtain the Kerberos ticket and AFS token ''within'' the PAG, the tokens will apply only to the current process (usually a shell) and the processes started from it (its children).
  47  * If you obtain the Kerberos ticket and AFS token ''outside'' the PAG, the tokens will apply to all processes running under your Unix username (well, to those that are not members of some existing PAGs, of course).
  48
  49 To "enter" a PAG, you start shell named '''/usr/bin/pagsh.openafs'''. With SSH, even though you find yourself in the shell of preference, a PAG is created for you just beforehand. (Verify by running '''id''' and noticing one numerical, untranslated entry such as 1105575254). Once within a PAG, there is basically no way to "escape" from it, so in effect, it is not possible to affect Kerberos/AFS identity of any of your other running processes by SSH-ing into a machine and kinitting as a different principal or obtaining different AFS tokens - they only apply to your current shell and its subprocesses.
  50
  51 In contrast, when unattended processes are started in your name, they are free of a PAG so you have the freedom of choice - influencing all "pagless" processes running under your Unix username, or starting pagsh manually and restricting influence to the current process and its children.
  52
  53 This quickly leads to two possible strategies:
  54
  55  1. Have one pagless process running which is refreshing USER.daemon token periodically (to keep it from expiring), and also run all scripts pagless - they will automatically find themselves to have that USER.daemon token.
  56
  57  1. Invoke all your scripts with shell '''/usr/bin/pagsh.openafs''' (can be in the #! "shebang" line) and obtain AFS token immediately after. Then rely on all subprocesses started from that script to inherit the obtained identity.
  58
  59 == Unattended Access Privileges ==
  60
  61 In any case, using file ''/etc/keytabs/user.daemon/USER'' to obtain your Kerberos/AFS identity will "log you in" into AFS as USER.daemon, not USER. Therefore, make sure that all directories you want to access from unattended scripts have read or write permission for USER.daemon in addition to USER.
  62
  63 For example, here's how the permissions look for your ~/Maildir/ which gives USER.daemon write access:
  64 {{{
  65 $ fs la ~/Maildir/
  66
  67 Access list for /afs/hcoop.net/user/U/US/USER/Maildir/ is
  68 Normal rights:
  69   system:administrators rlidwka
  70   USER rlidwka
  71   USER.daemon rlidwka
  72 }}}
  73
  74 To give read permission on a directory, use
  75 {{{
  76 fs sa DIRECTORY USER.daemon read
  77 }}}
  78
  79 To give write permission on a directory, use
  80 {{{
  81 fs sa DIRECTORY USER.daemon write
  82 }}}
  83
  84 Note that we mention directory permissions only - in AFS, there are no file permissions. Directory permissions apply to all contained files, except subdirectories. Each subdirectory defines its own permissions. When new subdirectories are created, they inherit the ACL list from the parent directory. If you want to change ACLs on an existing directory tree, just use the '''fsr''' command in place of '''fs''', with the same arguments.
  85
  86 = Recipes and Examples =
  87
  88 While you can use '''kinit''' to obtain tokens, we will use '''k5start''' in all examples. '''K5start''' is equivalent or better to '''kinit''' for all purposes.
  89
  90 == Creating the Directories Used in Examples ==
  91
  92 Create a directory that will contain your local executables and give USER.daemon read permission to it:
  93
  94 {{{
  95 $ mkdir ~/bin/
  96 $ fs sa ~/bin USER.daemon read
  97 }}}
  98
  99 Make sure your {{{~/.bash_profile}}} or equivalent file has ~/bin/ at the beginning of PATH, by enabling this within {{{~/.bash_profile}}}:
 100
 101 {{{
 102 # set PATH so it includes user's private bin if it exists
 103 if [ -d ~/bin ] ; then
 104     PATH=~/bin:"${PATH}"
 105 fi
 106 }}}
 107
 108 Create a directory that will contain PID files for all your user processes:
 109
 110 {{{
 111 $ mkdir ~/.run
 112 $ fs sa ~/.run system:anyuser rl
 113 $ fs sa ~/.run USER.daemon write
 114 }}}
 115
 116 == Script to Run a Particular Service Within Pagsh ==
 117
 118 A wrapper script that runs a user-specified daemon is provided on Mire as {{{run-in-pagsh}}}.  When calling it, the first argument should be a unique name with no spaces that describes the daemon, and then provide the commandline for calling that daemon afterwards.  Be sure to follow the instructions in the previous section for creating a {{{~/.run}}} directory with correct permissions.
 119
 120 Here is an example of calling this script.
 121
 122 {{{
 123 run-in-pagsh interserver ~/interchange/bin/interchange
 124 }}}
 125
 126 The script may be viewed [http://git.hcoop.net/?p=hcoop/misc.git;a=blob_plain;f=scripts/run-in-pagsh;hb=HEAD here].