RootInstance -> root-instance.mdwn
authorGreg Price <price@mit.edu>
Mon, 21 Sep 2009 00:26:10 +0000 (20:26 -0400)
committerGreg Price <price@mit.edu>
Mon, 21 Sep 2009 00:26:10 +0000 (20:26 -0400)
doc/RootInstance [deleted file]
doc/root-instance.mdwn [new file with mode: 0644]

diff --git a/doc/RootInstance b/doc/RootInstance
deleted file mode 100644 (file)
index d7a64a6..0000000
+++ /dev/null
@@ -1,38 +0,0 @@
-= Root and Extra Instances =
-
-This page explains why you want a ''root instance'' `joeuser/root@ATHENA.MIT.EDU` and an ''extra instance'' `joeuser/extra@ATHENA.MIT.EDU`, how to get them, and how to use them well.
-
-=== Background ===
-
-There are three parts of a Kerberos name: a ''principal'', an optional ''instance'', and a ''realm''. The principal is typically your username (for Kerberos identities belonging to a user), and the realm, at MIT, is usually ATHENA.MIT.EDU. (Other realms you may see are CSAIL.MIT.EDU, ZONE.MIT.EDU, CS.CMU.EDU, etc.) For the Kerberos identity you typically regard as your own, the one that you use to log in to Athena with your regular password, the instance is null (empty). However, you can ask for additional instances, usually a "root" or "extra" instance. You can use them in places where you wouldn't want to use your regular Athena password. You usually write a non-null instance as, e.g., joeuser/root@ATHENA.MIT.EDU.
-
-The entire triplet is also often referred to as a principal or instance, depending on context: "There are two Kerberos principals that can log in to this server, namely, my extra instance and my root instance. My null instance can't log in."
-
-=== Typical use ===
-
-Root instances are often used when logging in to servers that have some security import. Most students regularly log in to Athena cluster workstations and quickstations and often type their password on other people's laptops to SSH or get to webmail. This puts the password at huge risk for theft. Athena passwords [http://tech.mit.edu/V125/PDF/N20.pdf have been stolen from clusters in the past], so it's not the wisest idea to let servers that you're asking hundreds of people to log into and use be controlled by a password you're typing everywhere.
-
-So you get a root instance, and only type the root instance password on computers you trust and only when you need to. Many people only ever type it on their laptop, or on a freshly booted Live CD. Some people feel comfortable typing it on a few private Athena workstations (SIPB office heads are a common choice), but if an attacker has stolen your regular (null instance) password and installed a keylogger on your account, it doesn't matter where you're logging in if it's still your Athena account.
-
-You can also make things in Moira or AFS owned by your root instance, if you don't want your null instance to be able to mess with mailing lists or lockers. For Moira, make them owned by KERBEROS:yourname.root@ATHENA.MIT.EDU. (For legacy Kerberos 4 reasons Moira and AFS both use a dot instead of a slash to separate the principal and the instance.) For AFS, ask accounts or afsreq to get you a 'pts id', basically
-an account with the AFS servers, and then you can give bits to yourname.root and start blanching your root instance onto AFS groups.
-
-To use another instance, just specify it to the kinit command, e.g., "kinit joeuser/root".
-
-=== Handy scripts ===
-
-Because you would want to use your null instance tickets most of the time but your root instance tickets occasionally, a couple of people have developed shell scripts to make it easy to switch between them.
-
- * nelhage has the [http://web.mit.edu/nelhage/Public/krbroot krbroot command], which you use syntax like "krbroot ssh linerva" when you want to use your root instance for a command. You can also "krbroot shell".
- * quentin has [http://web.mit.edu/quentin/Public/mac-bashrc kdo], which is similar in spirit to krbroot, but designed for Mac OS X. It takes advantage of the fact that OS X's Kerberos implementation is better at handling multiple tickets.
- * geofft has [http://web.mit.edu/geofft/Public/bashrc.kpagsh kpagsh], a way of configuring your .bashrc to prompt you for tickets (null instance by default) if you start a shell and don't have tickets. If you want to switch tickets, you start a new shell, and also a new PAG, which lets you use multiple AFS credentials at once, too. It also modifies your prompt.
-
-These aliases are also careful to get shorter lifetime tickets that are marked nonforwardable. Some versions of SSH try to forward tickets by default. Since you might let your root instance tickets access many servers, but not trust all of these servers equally, you don't want your tickets to be forwardable. (Thankfully, recent Debian, Ubuntu, and OS X have turned off this default, but it's a good precaution.)
-
-=== Extra instances ===
-
-Another thing you might want is an ''extra instance''. Some people use these just like another root instance, with slightly lower security. But a common use is something _less_ secure than your null instance. For example, if you're writing a zephyrbot to run on a shared server like scripts.mit.edu, the zephyrbot will need Kerberos tickets to subscribe to zephyrs. But you don't want to leave your Kerberos password in a file in your locker, so you can leave your extra instance's password instead.
-
-=== Getting them ===
-
-You need to show up in person to IS&T User Accounts in N42 with a photo ID to obtain new Kerberos identities. For the reasons described above, being in control of your null instance and sending a zephyr or authenticated e-mail with it does not mean that you can go ahead and make changes to your root or extra instance too.  While you're there, be sure to ask for a pts id, if you want to use your tickets with AFS.
diff --git a/doc/root-instance.mdwn b/doc/root-instance.mdwn
new file mode 100644 (file)
index 0000000..777bfed
--- /dev/null
@@ -0,0 +1,108 @@
+[[!meta title="Root and Extra Instances"]]
+
+This page explains why you want a *root instance*
+`joeuser/root@ATHENA.MIT.EDU` and an *extra instance*
+`joeuser/extra@ATHENA.MIT.EDU`, how to get them, and how to use them
+well.
+
+## Background
+
+There are three parts of a Kerberos name: a *principal*, an optional
+*instance*, and a *realm*. The principal is typically your username
+(for Kerberos identities belonging to a user), and the realm, at MIT,
+is usually ATHENA.MIT.EDU. (Other realms you may see are
+CSAIL.MIT.EDU, ZONE.MIT.EDU, CS.CMU.EDU, etc.) For the Kerberos
+identity you typically regard as your own, the one that you use to log
+in to Athena with your regular password, the instance is null
+(empty). However, you can ask for additional instances, usually a
+"root" or "extra" instance. You can use them in places where you
+wouldn't want to use your regular Athena password. You usually write a
+non-null instance as, e.g., `joeuser/root@ATHENA.MIT.EDU`.
+
+The entire triplet is also often referred to as a principal or
+instance, depending on context: "There are two Kerberos principals
+that can log in to this server, namely, my extra instance and my root
+instance. My null instance can't log in."
+
+## Typical use
+
+Root instances are often used when logging in to servers that have
+some security import. Most students regularly log in to Athena cluster
+workstations and quickstations and often type their password on other
+people's laptops to SSH or get to webmail. This puts the password at
+huge risk for theft. Athena passwords [have been stolen from clusters
+in the past](http://tech.mit.edu/V125/PDF/N20.pdf), so it's not the
+wisest idea to let servers that you're asking hundreds of people to
+log into and use be controlled by a password you're typing everywhere.
+
+So you get a root instance, and only type the root instance password
+on computers you trust and only when you need to. Many people only
+ever type it on their laptop, or on a freshly booted Live CD. Some
+people feel comfortable typing it on a few private Athena workstations
+(SIPB office heads are a common choice), but if an attacker has stolen
+your regular (null instance) password and installed a keylogger on
+your account, it doesn't matter where you're logging in if it's still
+your Athena account.
+
+You can also make things in Moira or AFS owned by your root instance,
+if you don't want your null instance to be able to mess with mailing
+lists or lockers. For Moira, make them owned by
+`KERBEROS:yourname.root@ATHENA.MIT.EDU`. (For legacy Kerberos 4 reasons,
+Moira and AFS both use a dot instead of a slash to separate the
+principal and the instance.) For AFS, ask accounts or afsreq to get
+you a 'pts id', basically an account with the AFS servers, and then
+you can give bits to yourname.root and start blanching your root
+instance onto AFS groups.
+
+To use another instance, just specify it to the kinit command, e.g.,
+`kinit joeuser/root`.
+
+## Handy scripts
+
+Because you would want to use your null instance tickets most of the
+time but your root instance tickets occasionally, a couple of people
+have developed shell scripts to make it easy to switch between them.
+
+ * nelhage has the [krbroot
+   command](http://web.mit.edu/nelhage/Public/krbroot), with which you
+   use syntax like "krbroot ssh linerva" when you want to use your
+   root instance for a command. You can also "krbroot shell".
+
+ * quentin has [kdo](http://web.mit.edu/quentin/Public/mac-bashrc),
+   which is similar in spirit to krbroot, but designed for Mac OS
+   X. It takes advantage of the fact that OS X's Kerberos
+   implementation is better at handling multiple tickets.
+
+ * geofft has [kpagsh](http://web.mit.edu/geofft/Public/bashrc.kpagsh),
+   a way of configuring your .bashrc to prompt you for tickets (null
+   instance by default) if you start a shell and don't have
+   tickets. If you want to switch tickets, you start a new shell, and
+   also a new PAG, which lets you use multiple AFS credentials at
+   once, too. It also modifies your prompt.
+
+These aliases are also careful to get shorter lifetime tickets that
+are marked nonforwardable. Some versions of SSH try to forward tickets
+by default. Since you might let your root instance tickets access many
+servers, but not trust all of these servers equally, you don't want
+your tickets to be forwardable. (Thankfully, recent Debian, Ubuntu,
+and OS X have turned off this default, but it's a good precaution.)
+
+## Extra instances
+
+Another thing you might want is an *extra instance*. Some people use
+these just like another root instance, with slightly lower
+security. But a common use is something *less* secure than your null
+instance. For example, if you're writing a zephyrbot to run on a
+shared server like `scripts.mit.edu`, the zephyrbot will need Kerberos
+tickets to subscribe to zephyrs. But you don't want to leave your
+Kerberos password in a file in your locker, so you can leave your
+extra instance's password instead.
+
+## Getting them
+
+You need to show up in person to IS&T User Accounts in N42 with a
+photo ID to obtain new Kerberos identities. For the reasons described
+above, being in control of your null instance and sending a zephyr or
+authenticated e-mail with it does not mean that you can go ahead and
+make changes to your root or extra instance too.  While you're there,
+be sure to ask for a pts id, if you want to use your tickets with AFS.