Toolserver/Getting started

From Meta, a Wikimedia project coordination wiki

Jump to: navigation, search
Toolserver Wikimedia Community Logo-Toolserver.svg
Shortcut:
TS/U/T

This page provides a tutorial and reference serves as a tutorial and reference on getting started on the toolserver, in the chronological order a first-time user would encounter the tasks.

Contents

[edit] Get an account

Before you can run your projects on Wikimedia toolserver, you need to have an account. You can a new account, but you should know the rules very well before making a request.

After your request has been approved, a message will be added to your user talk page. If you are a member of more than one Wikimedia wiki, the message will usually be posted on your talk page on your primary wiki. The message asks you to provide information to complete your request, as explained below.

The first three are straightforward! The last one is described in the following.

[edit] Generate SSH key

SSH (secure shell) is a method for securing transferred data. To use SSH, you must first create a private and a public key, which together are called a key pair. You can give out your public key, but the private key should never be shared with anyone or stored where it can easily be accessed by others. Your private key should have a passphrase, so that it cannot be used by someone else who might steal it.

When you send data to the toolserver, it will check that your public key (which you will send later) matches your private key. You can then send encrypted data to the server, which will use your public key to decrypt it (make it readable again).

[edit] Unix/Linux/Mac

  1. Generate
    1. Run ssh-keygen -t dsa from the terminal. If the program does not exist, you will need to install ssh client (see your distribution's documentation). For example, Ubuntu users can run sudo apt-get install ssh-keygen to download and install it.
    2. When prompted, accept the default filename.
    3. When prompted, provide a strong passphrase (a secret sentence only you will ever know, like a password). Your private key will be ~/.ssh/id_dsa, and your public key will be the same with .pub appended.

Note: You need your private key file to connect to the toolserver. Make sure you store your private key file in a secure, memorable location on your computer. If it is deleted or lost, you will need to start over and set up your account again, which will also mean more work for toolserver administrators.

[edit] Windows

  1. Download PuTTYgen.exe (download page), a free SSH key generator.
  2. Run PuTTYgen.exe. Inside the big blank area in the upper half of window, move your mouse cursor randomly. Remember to keep your mouse pointer over the big blank area when you are moving it. When the progress bar on the right reaches the end, the upper half of the window will change to show you your public key.
  3. In the "Key passphrase" box, type a strong passphrase (a secret sentence only you will ever know, like a password).
  4. In the "Confirm passphrase" box, type the same passphrase.
  5. Click on "Save public key", and save the public key as a file on your desktop (you can name it toolserver.public, for example).
  6. Click on "Save private key", and save the private key as a separate file in a different location (you can name it toolserver.ppk for example).

Note: You need your private key file to connect to the toolserver. Make sure you store your private key file in a secure, memorable location on your computer. If it is deleted or lost, you will need to start over and set up your account again, which will also mean more work for toolserver administrators.

[edit] Send the information

Now you need to send the information to the toolserver administrators so they can set up your account.

  1. Address an email to Zedler-admins.png.
  2. Attach your public key file.
  3. Write the following information in the email body:
    • your real name;
    • your wiki nickname;
    • your preferred user name on the toolserver;
    • your SSH public key.
  4. Send.

[edit] Log in to shell

After you set up your account, you can log in to the shell (also known as the command line, terminal, or command prompt). The shell is a text-only environment that allows you to run commands on the toolserver, such as to run a script you've written or kill a script or database query. The Toolserver uses Linux, so all Bash commands are available (except any restricted commands); see a list of Bash commands.

The steps below explain how to configure your client and log in; transferring files is explained in the next section, but you should do this first to configure your software.

Some useful shell commands (after you log in):

[edit] Unix/Linux/Mac

Note: This tutorial explains how to use standard command-line tools. To use graphical tools, see their documentation and adapt the following instructions.

  1. Download
    1. Run ssh. If the command is not found, you will need to install the ssh client or use a different program(see your distribution's documentation). For example, Ubuntu users can run sudo apt-get install ssh in the terminal to install the required tools.
  2. Connect
    1. Run ssh user_name@login.toolserver.org. (If you're not using ssh, read the appropriate manual page to determine the correct command).
    2. When prompted, enter the passphrase for your private key.

If you entered the above correctly, a toolserver message should appear and the cursor will blink under it. Read the messages printed on the screen first. The blinking cursor means that the toolserver shell is waiting for you to enter commands (see list of commands). Remember that you are responsible for any problem caused by running faulty commands.

[edit] Windows

  1. Download
    1. To log in to the toolserver, you will need a SSH client such as putty.exe (download).
  2. Configure (first time only)
    1. Run PuTTY.exe by double-clicking it. A window named "PuTTY Configuration" should appear.
    2. In the "Session" tab, type login.toolserver.org in the "Host Name" box. (Leave the other options on this page alone for now.)
    3. Find "Connection" on the left menu, and click the "+" box to show more options (if it is already expanded, "+" will change to "-").
    4. Under "Connection", find and expand "SSH", then select "Auth".
    5. Click the browse button on the right side, and browse and locate your private key file. Select it and click the Open button.
    6. Click "Session" on the left menu to return to the first box you saw.
    7. In the first "Saved Session" box, type a name to save your settings (toolserver is a good name).
    8. Click the "Save" button beside the boxes in that section. This will save your settings so you don't need to enter them again in the future.
    9. Close PuTTY (not necessary, but helps you see what that did in the next step).
  3. Connect
    1. Run PuTTY.exe and double-click "toolserver" (or whatever name you chose) under "Saved Sessions". A new window should appear.
    2. When prompted, enter your toolserver user name. (note that this will be in lowercase)
    3. When prompted, enter the passphrase you created for your private key. (It will not show you what you type; this is normal! Just enter it correctly and press Enter.)

If you entered the above correctly, a toolserver message should appear and the cursor will blink under it. Read the messages printed on the screen first. The blinking cursor means that the toolserver shell is waiting for you to enter commands (see list of commands). Remember that you are responsible for any problem caused by running faulty commands.

Retrieved from "http://meta.wikimedia.org/wiki/Toolserver/Getting_started"