doc/using-athena.mdwn

   1 # Using Athena
   2
   3 **Intended Purpose:**
   4
   5 * This article will help you answer the question “how can I have a website with an MIT domain”?
   6 * The website you’re making is static (otherwise [scripts](scripts.mit.edu) might be a better option!)
   7 * To be below the level of [afs-and-you](https://sipb.mit.edu/doc/afs-and-you/)
   8
   9 **Prerequisites:**
  10
  11 * Familiarity with using a terminal (experimented with basic commands like cd, ls, mkdir, etc.)
  12
  13
  14 ## Connecting to Athena
  15
  16 SSH (Secure Shell) allows a computer to remotely login into another computer/server while making use of adequate security features. Thankfully, most operating systems have an SSH program already built in and no additional installs are needed on your machine. You can SSH into Athena by following these steps.
  17
  18
  19 **Note:** If your computer does not have `ssh`, you could also use shellinabox, an online terminal for using Athena that can be found [here](https://athena.dialup.mit.edu/.) Though, it’s not ideal as it will log you off if you’re idle for a few minutes (which is probably not what you want when you’re following a guide like this).
  20
  21
  22 First, open your OS’s respective terminal. Then enter
  23
  24 ```
  25 ssh [kerberos]@athena.dialup.mit.edu
  26 ```
  27
  28
  29 but replacing `[kerberos]` with your kerberos/Athena username. So, for example, if your username is `aphacker`, you would type into the terminal `ssh aphacker@athena.dialup.mit.edu`.
  30
  31 If successful, ssh will tell you (on your _first_ connection):
  32
  33 ```
  34 Host key not found from the list of known hosts.
  35 Are you sure you want to continue connecting (yes/no)?
  36 ```
  37
  38 Type `yes', and now it will respond:
  39
  40  ```
  41 Host 'athena.dialup.mit.edu' added to the list of known hosts.
  42 aphacker's password:
  43 ```
  44
  45 Type your password and press Enter. Note, you will not see any characters appear as you type your password; this is a security feature.
  46
  47 Now you’ll be prompted to complete two-factor authentication via Duo.
  48
  49 ```
  50 Enter a passcode or select one of the following options:
  51  1. Duo Push to XXX-XXX-1234
  52  2. Phone call to XXX-XXX-1234
  53  3. SMS passcodes to XXX-XXX-1234
  54 Passcode or option (1-3):
  55 ```
  56
  57 Type an option number and press Enter. Complete your two-factor authentication. With luck, the terminal will print a series of startup text, finally ending with a line that reads
  58
  59 ```
  60 aphacker@scrubbing-bubbles:~$
  61 ```
  62
  63 You have now been dropped into Athena! Like the terminal on your computer, you can type commands and they will execute. For example, you can type `pwd` and see
  64
  65 ```
  66 aphacker@scrubbing-bubbles:~$ pwd
  67 /afs/athena.mit.edu/user/a/p/aphacker
  68 ```
  69
  70 ## Serving a website from AFS
  71
  72 Now that you’re in Athena, you can access the files in MIT’S AFS. Right now, you are in your home directory for MIT’s AFS. There are several subdirectories in your home directory, but the important one to focus on right now is `~/www`.
  73
  74 Files in your `~/www` directory are available on the internet through a URL, specifically via the form factor of `https://web.mit.edu/aphacker/www/`. If you go to that URL right now though, you won’t see anything (besides an error). We can change that by populating that directory with the content that makes up a small web page.
  75
  76 First, `cd` into the `www` directory.
  77
  78 ```
  79 aphacker@scrubbing-bubbles:~$ cd www
  80 aphacker@scrubbing-bubbles:~/www$
  81 ```
  82
  83 Then, run the following command to make a file named `index.html` with a simple HTML5 template like so
  84
  85 ```
  86 aphacker@scrubbing-bubbles:~/www$ echo '<!DOCTYPE html><title>Hello World!</title>' > index.html
  87 ```
  88
  89 If you now visit your URL at `https://web.mit.edu/aphacker/www/`, you will see the web page you made! It’s a blank page with the title “Hello World!”. Note, this change is sometimes not immediate and will take a few minutes, but never hours.
  90
  91 You can edit the webpage you just made by running a text editor like [nano or Vim](https://xkcd.com/378/).
  92
  93 ```
  94 aphacker@scrubbing-bubbles:~/www$ nano index.html
  95 ```
  96
  97 This should bring up a screen with the current contents of `index.html`, which you can now edit. You can read more about how to use nano elsewhere, and edit your file as you wish.
  98
  99 ## Using SCP
 100
 101 If you feel unready to strictly edit files via the remote shell, using a package called SCP (Secure Copy), which is bundled with SSH, might be of interest. It allows you to copy files from your computer to AFS and vice-versa.
 102
 103 To copy a file from your computer to AFS, open your terminal and enter a command like
 104
 105 ```
 106 scp file.txt aphacker@athena.dialup.mit.edu:~
 107 ```
 108
 109 This will copy a file called `file.txt` to your home directory in AFS. You’ll have to do two-factor authentication with Duo, similar to SSH.
 110
 111 You can read SCP’s man page (on the terminal via `man scp` or online at [man7](https://man7.org/linux/man-pages/man1/scp.1.html)) or other reference sheets (like [tldr-pages](https://tldr.ostera.io/scp) for more information about how to use SCP.
 112
 113 ## What next?
 114
 115 ### Additional readings
 116
 117 For more information about what AFS is, visit:
 118
 119 * [AFS at MIT - An Introduction](http://kb.mit.edu/confluence/display/istcontrib/AFS+at+MIT+-+An+Introduction)
 120 * [AFS and You](https://sipb.mit.edu/doc/afs-and-you/)
 121 * [AFS Locker Maintenance Guide](http://kb.mit.edu/confluence/display/istcontrib/AFS+Locker+Maintenance+Guide)
 122
 123 ### Tips/tricks
 124
 125 To use Visual Studio Code (VSC) to interact with Athena, follow these steps:
 126
 127 1. In your machine’s VSC, install the [“official” ssh extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
 128 2. SSH into Athena and use your text editor to edit into `~\.bashrc`. Then, append this command at the end of the file (in a new line): `find ~/.vscode-server/ -name 'vscode-remote-lock.{kerberos}.*' -delete`. Here, you replace `{kerberos}` with your kerberos.
 129 3. Follow the extension’s steps for establishing a SSH connection.