$Id: owl-screen.txt,v 1.10 2008/08/07 23:04:48 kchen Exp $ If you're a heavy zephyr user, you may have wished that you could read your zephyrs at one computer, go to another computer, and then continued reading where you left off. With the program named screen, this is possible. However, there are some complications with using screen in the MIT environment, since various Kerberos and AFS settings must be set correctly for this to work, to ensure that you continuously have Kerberos tickets and AFS tokens, so that you continually send authentic zephyrs, and so that owl can read your settings, and if you have logging configured, log your zephyrs. ----------------- QUICKSTART ----------------- 1. Pick a machine to host your screen session on. If you don't know of any options, linerva.mit.edu is a good choice. 2. ssh to that machine. 3. Run "add kchen". You may want to add this to your ~/.environment file. 4. Run "owl-screen". Your screen session is now ready. Once you start the screen session, you'll get a zephyr telling you that you need to get renewable tickets. Press C-a C-c to open a new screen window, and run "kinit -l7d" , and type your password. (Note: the character after "-" is the lowercase form of the letter L, not the number 1.) Press C-a 0 to return back to your barnowl window. When you're ready to log out, press C-a d to "detach" your screen, and then type "exit" or "logout" to log out. Later, when you want to "reattach" your screen, ssh to the machine again, and run "screen -x". In six days, a zephyr will inform you that you need to renew your tickets. Press C-a 1 to switch to the shell you opened earlier, and run "kinit -l7d" again. If you'd like your screen to automatically show up when you log in at a physical Athena machine, add the following to your .environment file: add kchen gnu setenv ZEPHYR_HOME "linerva.mit.edu" setenv ZEPHYR_CLIENT "owl-startup" ZEPHYR_HOME should be set to the machine you picked earlier. Adding these lines will also prevent the graphical zwgc client from appearing when you ssh into certain machines, preventing duplicate zephyrs. ----------------- DETAILS ----------------- The details about how some parts of the scripts work are out of date, but the overall ideas are still accurate. 1. Kerberos tickets As the Kerberos web page at http://web.mit.edu/kerberos/ notes: Kerberos is a network authentication protocol. It is designed to provide strong authentication for client/server applications by using secret-key cryptography. When using an Athena machine (or specifically configured non-Athena machine), you can use Kerberos to authenticate yourself to various services. You do this by acquiring Kerberos tickets from the MIT Kerberos server, and then showing that ticket to other services that use Kerberos, such as zephyr. To get Kerberos tickets, you can type: kinit By default, this will give you tickets that last for 10 hours. However, for using zephyr in screen, you probably want longer tickets, so that you don't have to type your password every 10 hours. The -l option to kinit allows you to specify that you want to get tickets that last for an amount of time other than 10 hours. For example, if you wanted to get tickets for 1 day (the maximum MIT ticket lifetime), you could type: kinit -l1d where the d stands for days. This lets you type your password every 1 day, rather than every 10 hours. Since your screen session is going to last longer than that, though, it's still rather annoying to type in your password more than once every day. Here's where renewable Kerberos tickets come in. Note that the command "renew" on Athena doesn't actually renew tickets -- instead, it gets you new ones. Renewable tickets let you take your non-expired tickets and extend their expiration time. To use renewable tickets, you can use the -r option to kinit. kinit -l1d -r7d would give you Kerberos tickets that are valid for 1 day, and renewable for 7 days (the MIT maximum). If you renew your tickets before they expire, the expiration date of the tickets becomes 1 day after the time you renew them. However, you cannot renew them indefinitely -- the maximum expiration time in this example is 7 days from the time you get the renewable tickets. To renew your renewable tickets before they expire, you can type: kinit -R Now that we have renewable tickets, we just need to renew them before they expire. Typing "kinit -R" is certainly easier than typing one of the other kinit commands and typing in a password, but it's still not as convenient as it could be. Therefore, we can write a script such as the following to run "kinit -R" for us every hour. #!/usr/bin/env perl while (1) { system("kinit -R"); system("krb524init"); sleep(3600); } The krb524init line isn't needed for Athena machines, but is needed on some other machines to generate Kerberos version 4 tickets from the default Kerberos version 5 tickets. We'll augment this basic script later on in this tutorial. 2. AFS tokens Now that we have Kerberos tickets, we can get AFS tokens. Tokens let us authenticate to AFS, and read and write to restricted directories. We can use the Kerberos tickets we obtained to authenticate to AFS and get AFS tokens. To do this, we can run: aklog athena to get Athena AFS tokens. If we wanted to get Athena and SIPB AFS tokens, we would run: aklog athena sipb (These are actually shortened forms of the commands -- the full form would be: aklog athena.mit.edu sipb.mit.edu ) The AFS tokens expire at the same time that the Kerberos tickets expire. Therefore, when we renew our Kerberos tickets, we'll also want to get new AFS tokens. We can augment the script that we have to contain: #!/usr/bin/env perl while (1) { system("kinit -R"); system("krb524init"); sleep(1); system("aklog athena sipb"); sleep(3600); } Now, every hour, immediately after renewing our Kerberos tickets, we get new AFS tokens. This script can be run by typing: athrun kchen cont-renew & Alternatively, if you have the kchen locker attached, you can run: cont-renew & 3. Kerberos environment variables Kerberos stores your Kerberos tickets in two files, usually in /tmp. The files that your tickets are stored in are named something like /tmp/krb5cc_p30552 and /tmp/tkt_p30552. If we want to use different files for Kerberos tickets (we'll see why we might want to do this later), we can set the KRB5CCNAME (for Kerberos 5 tickets) and KRBTKFILE (for Kerberos 4 tickets) environment variables. For example, if we wanted to save our Kerberos tickets as /tmp/krb5cc_${USER}_screen and /tmp/tkt_${USER}_screen, we could run: In tcsh: setenv KRB5CCNAME /tmp/krb5cc_${USER}_screen setenv KRBTKFILE /tmp/tkt_${USER}_screen In bash and sh: KRB5CCNAME=/tmp/krb5cc_${USER}_screen; export KRB5CCNAME KRBTKFILE=/tmp/tkt_${USER}_screen; export KRBTKFILE 4. AFS Process Authentication Groups Unlike Kerberos tickets, AFS tokens are not stored in files; instead, they are stored in memory. A PAG (Process Authentication Group) is a container for tokens. All programs running in a particular PAG share the same tokens. If you want a separate container, you need to start a new PAG. To start a new PAG, you can run: newpag This starts your current shell in a new PAG. Alternatively, to run sh in a new PAG, you can run: pagsh You won't need to run these commands manually, but they're useful to understand some of the later material. 5. screen screen is a program that allows you to run programs within it, go to a different machine, remotely access the original machine, and then reattach your screen, so that you can see your original program. In the context of this document, you could start owl on one machine, go to a different machine, ssh into the original machine, and reattach the screen to continue reading your zephyrs right where you left off. On Athena, screen is located in the gnu locker. To start it: athrun gnu screen Or, if you have the gnu locker attached, screen If you want to start an initial program, like owl-beta, you can run: screen owl-beta 5. The problems with screen, Kerberos, and AFS On a typical Athena machine, your Kerberos tickets and AFS tokens get destroyed when you log out. This is normally convenient, so you don't have to worry about other people then sitting down at a cluster machine and then using your Kerberos tickets in /tmp to masquerade as you, if you forget to manually destroy them. When using screen, though, this is problematic. If you sit down at a machine (or ssh into a machine), at some point, you may want to log out, but keep your screen active. If you start screen normally, detach it, and log out, your screen session will no longer have Kerberos tickets and AFS tokens. This is because it was using the same Kerberos tickets as your original login shell, and when you logged out, the Kerberos tickets were destroyed. Similarly, because screen was in the same PAG, when you logged out, the AFS tokens corresponding to the PAG were destroyed, and your screen session (and by extension owl) won't have access to AFS. If owl needs to read any of your configuration files, or if you are trying to log your zephyrs to AFS, it will be unable to. 6. How to solve the screen problems We can use the things we previously learned to solve this problem. 1. We'll want to use separate ticket files for screen such that when the original ticket files are destroyed, we'll still have tickets for screen. 2. We'll want to start screen in a new PAG so that the tokens it uses are separate from the original login shell's tokens, so that when the tokens for the original PAG are destroyed, we'll still have tokens for screen. 3. We'll want to get renewable tickets for screen such that we only need to type our password once a week. To do these things, we might run the following chain of commands: screen newpag setenv KRB5CCNAME /tmp/krb5cc_${USER}_screen setenv KRBTKFILE /tmp/tkt_${USER}_screen kinit -1d -r7d owl-beta However, this has two problems: 1. It's a lot of commands to manually type. 2. This puts owl in a new PAG, but other windows in screen are still in the same PAG as the original login shell's PAG, leading to confusion and inconsistency. To solve this problem, we can put screen itself in a new PAG. If we try to run this sequence of commands, however, we run into other problems: newpag setenv KRB5CCNAME /tmp/krb5cc_${USER}_screen setenv KRBTKFILE /tmp/tkt_${USER}_screen kinit -1d -r7d screen owl-beta When we detach screen, we still need to exit the PAG before we can log out. However, we won't be able to exit the PAG because screen is still running inside it. Therefore, we write a script that uses pagsh to get around this problem. The following script, located in /mit/kchen/bin/owl-screen, makes use of what we've previously discussed: #!/usr/athena/bin/pagsh # get AFS tokens for the screen session # also, note that we are now in a new PAG (because of pagsh) aklog # use separate kerberos tickets for screen # even if we accidentally (or intentionally) log out, screen # and owl will still have tickets NEWKRB5=/tmp/krb5cc_${USER}_screen NEWKRB4=/tmp/tkt_${USER}_screen # copy the tickets we obtained on login to the screen tickets cp $KRB5CCNAME $NEWKRB5 cp $KRBTKFILE $NEWKRB4 # and actually use the new tickets KRB5CCNAME=$NEWKRB5; export KRB5CCNAME KRBTKFILE=$NEWKRB4; export KRBTKFILE # finally, start owl in screen # name the screen owl so we can reattach the right screen later # make color work on Sun machines with TERM=xtermc # actually, we no longer use xtermc. Instead, copy # /usr/share/terminfo/s/screen* from a Linux machine to # /usr/share/lib/terminfo/s on the Sun machine screen -S owl owl-beta This lets us start owl in a screen, and sets up the new PAG and the Kerberos environment variables for us. Therefore, to configure everything we need to allow owl to work correctly for one week without typing in our password sooner than that, we can run the following commands: add kchen owl-screen C-a C-c kinit -l1d -r7d cont-renew C-a 0 The C-a C-c starts a new owl window, so we can get our renewable Kerberos tickets. The C-a 0 switches back to the original window, so we can read our zephyrs in owl. 7. How to attach and detach a screen session We know how to start our screen session now, but we haven't mentioned how to detach it or attach it. To detach a screen session (for example, if we want to log out), press C-a d. screen continues to run, but is no longer active. To reattach a screen session, run one of the following commands (as listed in the screen man page): -d -r Reattach a session and if necessary detach it first. -d -R Reattach a session and if necessary detach or even create it first. -d -RR Reattach a session and if necessary detach or create it. Use the first session if more than one session is available. -D -r Reattach a session. If necessary detach and logout remotely first. -D -R Attach here and now. In detail this means: If a session is running, then reattach. If necessary detach and logout remotely first. If it was not running create it and notify the user. This is the author's favorite. -D -RR Attach here and now. Whatever that means, just do it. Note: It is always a good idea to check the status of your ses- sions by means of "screen -list". -x Attach to a not detached screen session. (Multi display mode). I prefer the -x option, since it means that you don't need to reattach your screen elsewhere if it was previously attached. 8. How to start and reattach screens with owl automatically By default, when you log in to an Athena machine while sitting in front of it, zwgc starts up by default. Instead of launching zwgc, though, you might want to have your screen automatically reattached. We can use the following script, located in /mit/kchen/bin/owl-startup, to do that: #!/bin/sh # if no home machine is specified, use scyther.mit.edu if [ "x$ZEPHYR_HOME" = "x" ]; then ZEPHYR_HOME="scyther.mit.edu" fi # don't do anything if we're just ssh'ing if [ "x$XSESSION" != "x" ]; then # start zwgc with no subs # this sends a login notification when appropriate, so even though # we're using screen and owl elsewhere, people can still find us # this also ensures zephyrs sent by programs upon startup will # still send the zephyr, and not hang when started with & zwgc -f /dev/null -subfile /dev/null zctl cancel if [ "$HOST" = "$ZEPHYR_HOME" ]; then # we're on our home machine! # see if we already have a screen named owl OWLSCREEN=`screen -list | grep owl` if [ "x$OWLSCREEN" = "x" ]; then # no screen named owl exists # create a new one with owl-screen # owl-screen will take care of kerberos, AFS, and naming the screen xterm -geometry 80x48-0+280 -title owl -e owl-screen &> /dev/null & else # one already exists # reattach it xterm -geometry 80x48-0+280 -title owl -e screen -x owl &> /dev/null & fi else # we're not on our home machine... # ssh to it and reattach the screen named owl xterm -geometry 80x48-0+280 -title owl -e ssh -t $ZEPHYR_HOME screen -x owl &> /dev/null & fi fi Then, to make this happen automatically instead of zwgc starting, in your .environment file, add the lines: add kchen gnu setenv ZEPHYR_HOME "scyther.mit.edu" setenv ZEPHYR_CLIENT "owl-startup" You should change the ZEPHYR_HOME line to use the machine you keep your screen on. There is one thing to note in this script: # start zwgc with no subs # this sends a login notification when appropriate, so even though # we're using screen and owl elsewhere, people can still find us # this also ensures zephyrs sent by programs upon startup will # still send the zephyr, and not hang when started with & zwgc -f /dev/null -subfile /dev/null zctl cancel In addition to the comments shown, there is one other thing to note. First, running some programs on Athena will automatically make you subscribed to personal zephyrs again, even though we previously cancelled all our subscriptions. For convenience, the zephyrs do not display (as specified with -f /dev/null). However, if your owl session in screen dies, people will still be able to send you personal zephyrs, but you will not see them. 9. Summary To set everything up: In .environment, add: add kchen gnu setenv ZEPHYR_HOME "scyther.mit.edu" setenv ZEPHYR_CLIENT "owl-startup" Change the ZEPHYR_HOME line to indicate which computer you have your screen on. If you do not run an Athena machine with X that you are normally sit at, or if you want to start your screen on a different computer, ssh to that computer and run owl-screen. If you do run an Athena machine with X that you are normally sit at that you want to start your screen on, owl and screen will be automatically started when you log in. Once screen is started, press C-a C-c to open a shell in a new window. Type: kinit -l1d -r7d cont-renew & This sets up renewable tickets and gets AFS tokens. Before a week is up, return to this shell (with C-a 1) and type: kinit -l1d -r7d Do not run the cont-renew line again, since it is still working in the background to renew your tickets. However, if your tickets and tokens have already expired, you may want to type: aklog athena sipb to immediately get new AFS tokens, instead of waiting one hour for cont-renew to do that for you. Then, press C-a 0 to return to owl. If you want to log out, press C-a d to return to your login shell, and type exit to log out. When you are not locally at an Athena machine and want to reattach your screen, ssh into the machine with screen and type a command similar to screen -x. However, if you sit down at an Athena machine with X, if you performed the configuration above, just log in, and your screen will be automatically reattached. 10. Miscellaneous notes If you make a copy of these scripts so that you can make your own customizations, you must set the permissions such that anybody can read and run it (or at least, you can read and run it when you do not have tokens). Otherwise, when you start the new PAG, you will be unable to read the rest of the script, and the script will not run. If you want to get updates on scripts in the kchen locker, you can add yourself to the moira list kchen-locker.