Difference between revisions of "Installation Guide"

From Bcontrol
Line 3: Line 3:
 
# the Matlab-side code (where you write your trial-to-trial control software, known as a "Protocol," and from where you control the State Machine.
 
# the Matlab-side code (where you write your trial-to-trial control software, known as a "Protocol," and from where you control the State Machine.
  
= For beginners that want to first simply learn to use the system =
 
  
For people that are just starting up, you'll most likely want to download the RTLinux-side code in its Emulator form, which you can do [[RTLinux:EmulatorSourceCode|here]]. The Emulator pretends that it is an RTLinux machine with a physical behavior box, but just runs on your laptop. So you can learn to use and test your software without need of an extra CPU or a behavior bix.
 
  
The Matlab-side code is the same as you use in when actually interacting with an RTLinux CPU. This is available both in [http://brodylab.princeton.edu/bcontrol_releases/ExperPort.zip zip format] or [http://brodylab.princeton.edu/bcontrol_releases/ExperPort.tar.gz tarred, gzipped format].
+
= Initial Requirements =
  
If you want to download the Matlab-side code as a developer, and therefore want access to the CVS repository, read on...
 
  
 +
Before, we begin let us make sure we have the following
  
-----
+
== Terminal or Shell ==
  
  
 +
==== Windows ====
 +
On Windows, download and install putty from [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html here] which will serve as a Terminal or Shell.
 +
(Recommended: Install putty using the [http://the.earth.li/~sgtatham/putty/latest/x86/putty-0.60-installer.exe Windows Installer] because it includes everything we would need now or in future: putty, puttygen, pageant etc.)
  
= For developers, core code and behavioral protocol developers =
+
==== Mac ====
 +
Mac already provides a built-in application called Terminal. It serves as the Terminal or Shell.
  
On your RTLinux machine, you will need RTLinux Source Code which can be downloaded [http://code.google.com/p/rt-fsm/source/checkout here].
+
== SVN Client ==
  
To download ExperPort (current name of the Matlab-side behavioral control project) from CVS, use it, and keep it up to date, you'll need:
+
==== Windows ====
- '''Matlab''' (We'll assume you have this already. :P )
+
The most popular SVN Client for Windows is TortoiseSVN. Download it [http://downloads.sourceforge.net/tortoisesvn/TortoiseSVN-1.6.11.20210-win32-svn-1.6.13.msi?download here] and install.
- any '''cvs''' client
 
- an '''ssh''' client (PuTTY used here)
 
- ... and to '''contact us''' later in the process for a username and to register your key
 
  
=='''Step 1''': Install PuTTY.==
+
==== Mac ====
 +
SVN Client for Mac is included with the Developer's Tools. So, install Developer's Tools completely that come with your Mac OS X Installation CD/DVD, if you haven't done it yet. Insert the CD/DVD and the option to install Developer's Tools will come up. Then proceed with on-screen instructions.
  
* Download putty (You'll need putty, puttygen, and plink at least, but you may as well have them all.) at http://www.chiark.greenend.org.uk/~sgtatham/putty
 
  
* Install PuTTY to any fixed place by running the install executable or simply downloading the individual executables to the same folder.
 
  
  
It is best to add this folder to the system path for ease of reference. To do so:
 
* Click Start, Control Panel, System.
 
* Choose the Advanced tab and press the Environment Variables button at the bottom. Select the System variable called Path from the lower window and click Edit. Add a semicolon to the end of the current path string (if there isn't one there already), then type in the full path of the directory containing the PuTTY executables (typically C:\Program Files\PuTTY;) and then OK your way out of the dialogs. Make sure not to leave any spaces before or after the path! (I.e., no spaces after or before a semicolon separating different path components, no spaces before the C:\.)
 
  
=='''Step 2''': Produce a public/private key pair.==
+
= Installation Guide for Beginners who want to first simply learn to use the system =
 +
 
 +
== RTLinux-Side ==
 +
 
 +
 
 +
=== Emulator ===
 +
For people that are just starting up, you'll most likely want to download the RTLinux-side code in its Emulator form. The Emulator pretends that it is an RTLinux machine with a physical behavior box, but just runs on your laptop. The Emulator shares most of its source code with the actual RT Linux source code. So you can learn to use and test your software without need of an extra CPU or a behavior box. It is thus a good place to start and learn to write protocols, interact with the state machine, and so on: you don't need an RT Linux machine for this, you just need your laptop. Instead of physical pokes, the Emulator GUI provides you with buttons that you click on with your mouse.
 +
 
 +
(''Note'': One currently very confusing thing about the Emulator's graphical interface: Ch. 00 is the Center poke; Ch. 01 is the Left poke, and Ch. 02 is the right poke. That is, they are ordered C,L,R, instead of L,C,R. We'll get around to changing that at some point.)
 +
 
 +
==== Windows ====
 +
 
 +
The latest emulator executable for Windows is ready for you to download and use right-away. Download the zip file [http://brodylab.princeton.edu/bcontrol_releases/FSMEmulator.2010.09.02.zip here]. Unzip it and double-click on FSMEmulator.exe to launch the emulator.
 +
(''Tip'': On Windows Vista and higher, right-click on FSMEmulator.exe and select "Run as Administrator" to launch the emulator.)
 +
 
 +
==== Mac ====
 +
 
 +
The latest emulator for Mac is not yet available in executable form (We are working on it). So, until we are done with it, follow these steps:
 +
 
 +
* Download and install Qt4 or higher (framework only) from [http://qt.nokia.com/downloads here].
 +
* Download the RTLinux Source code by typing the following command in your Terminal:
 +
<pre>$ svn checkout http://rt-fsm.googlecode.com/svn/trunk/ rt-fsm-read-only</pre>
 +
(''By doing the above, a new directory name 'rt-fsm-read-only' will be created in the current location and all the RTLinux-Source code will be downloaded into it.'')
 +
* Stay in the terminal, and type the following commands
 +
<pre>$ cd rt-fsm-read-only/emulator
 +
$ ./compile.sh clean
 +
$ ./compile.sh</pre>
 +
* The compilation might take a few minutes. After it is done, you can exit the terminal.  The emulator should now be available at ''rt-fsm-read-only/emulator/osx-x86/FSMEmulator.app''. Launch the emulator by double-clicking on it.
  
* Double-click the puttygen.exe icon to Run it.
 
* Select the SSH-2 DSA radio button at the bottom of the PuTTY Key Generator window.
 
* Press the Generate button.
 
* Add whatever short key comment you like.
 
* You may select a passphrase or elect not to. It is slightly easier not to use one, but if you do not, then anyone with your private key file can log in to our server as you. The cost of using a passphrase is having to double-click your private key file and enter the passphrase each time you start the computer.
 
* Pick a nice safe place (Not in code or data directories!) to save both your public and private keys-- that is, you have to click on both "Save public key" and "Save private key."
 
  
=='''Step 3''': Send us the public key so that we can grant you access to the server.==
+
=== Physical Machine ===
  
* Email brodyadmin at princeton dawt edu the '''public''' key file you saved (or its complete contents - it's text). I'll respond when your key is ready to be used - but you can continue through this guide meanwhile.
+
Alternatively, if you want to use the RTLinux-Side code on your physical RTLinux machine, download it using SVN Client from [http://code.google.com/p/rt-fsm/source/checkout here], and follow the instructions (available in a file named INSTALL_STEP_BY_STEP in the downloaded directory) on how to install source code on the actual RTLinux machine.
  
=='''Step 4''': Create a PuTTY session that uses that key to connect to our server.==
 
  
* Run putty.exe
+
== MATLAB-Side ==
  
The PuTTY dialog windows have changed slightly over time, but for the current version as of 2007.July.25:
+
The Matlab-side code is the same whether you are interacting with an RTLinux Machine or Emulator on your laptop. Download the code in [http://brodylab.princeton.edu/bcontrol_releases/ExperPort.zip zip] format (for Windows users) or [http://brodylab.princeton.edu/bcontrol_releases/ExperPort.tar.gz tarred/gzipped] format (for Mac Users). Unzip it and read the Startup Guide to start using it.
  
  
In the ''Sessions'' option group (initially displayed):
 
* Enter the following Host Name:  brodylab.princeton.edu
 
* Select SSH as the connection type (Port should be set to 22).
 
  
  
In the '''''Connection: Data''''' options subgroup (in the tree on the left):
 
* Type in the username you received from us in the Auto-login username field.
 
  
 +
= Installation Guide for Advanced Users (core code and behavioral protocol developers) =
  
In the '''''Connection: SSH''''' options subgroup (in the tree on the left):
+
== RTLinux-Side ==
* Select "2" as your Preferred SSH protocol version.
 
  
 +
On your RTLinux machine, you will need RTLinux Source Code which can be downloaded [http://code.google.com/p/rt-fsm/source/checkout here] or you can choose to use the emulator (read beginner's instructions above).
  
In the '''''Connection: SSH: Auth''''' options subgroup (in the tree on the left):
 
* Enter the location of the private key you created (whose corresponding public key you sent to us).
 
  
 +
== MATLAB-Side ==
  
Back in the '''''Sessions''''' options group (top of the tree on the left):
+
As a developer, downloading ExperPort (current name of the Matlab-side behavioral control project) from SVN repository, and keeping it up to date is your best option. Assuming you took care of the Initial Requirements (above), follow these simple steps to download ExperPort from SVN repositories:
* Choose a name for the session we've created (like brodylab) in the edit field below the text "Saved Sessions". DO NOT USE SPACES OR SPECIAL CHARACTERS; other programs may not treat them properly.
 
* Click Save.
 
  
 +
=== '''Step 1''': Generate public-private key pair ===
  
Now your connection is set up and you can '''double-click''' it in the list of sessions to test it.
+
==== Windows ====
  
'''Note that:'''
+
* Open PuTTYgen from Start->Programs->PuTTy
 +
* Select the SSH-2 DSA radio button at the bottom of the PuTTY Key Generator window.
 +
* Press the Generate button.
 +
* Add whatever short key comment you like.
 +
* You may select a passphrase or elect not to. It is slightly easier not to use one.
 +
* Pick a nice safe place (Not in code or data directories!) to save both your public and private keys-- that is, you have to click on both "Save public key" and "Save private key."
 +
* For example, you can save your private key as 'jmillers_key_for_brodylab.ppk' and public key as 'jmillers_key_for_brodylab.pub'.
  
- If you haven't confirmed your key with us yet, login will ask for a password (and PuTTY may report that your key has been rejected by the server).
+
==== Mac ====
  
- If you have chosen a passphrase for your key, you need to '''double-click''' your private key file (I suggest a shortcut on the desktop.) and enter your passphrase once each time your computer is started to start PAgeant - or else you would have to enter your passphrase on every CVS command!
+
* Open the Terminal window.
 +
* Make sure you are in your user directory. Lets say /Users/jmiller.
 +
* Type the following command: ''ssh-keygen''
 +
* While it is generating the keys, it will ask for a name for your key. Give a name to your key. Fox example let's say 'jmillers_key_for_brodylab'.
 +
* It will also ask you to type a passphrase. You may enter a passphrase or elect not to. It is slightly easier not to use one.
 +
* Two keys will be created now in /Users/jmiller directory. One is 'jmillers_key_for_brodylab' (this is the private key) and other is 'jmillers_key_for_brodylab.pub' (this is the public key).
 +
* Create a directory named '.ssh' (without the quotes), place your private key in it and modify the permissions of .ssh directory and this key as shown below:
  
- '''There is software to prevent malicious attempts to connect to the cvs server. If you fail to connect repeatedly, your IP will be banned for 10 minutes.'''
+
<pre>$ cd /Users/jmiller
 +
$ mkdir .ssh
 +
$ chmod 700 .ssh
 +
$ cp jmillers_key_for_brodylab .ssh/
 +
$ cd .ssh
 +
$ chmod 600 jmillers_key_for_brodylab</pre>
  
=='''Step 5''': Install a CVS client if you do not already have one.==
+
* Open ssh configuration file for editing as follows:
Which you use will not matter for our configuration.
 
  
TortoiseCVS and WinCVS are popular.
+
<pre>$ sudo su
 +
Password: <Enter your password here>
 +
$ nano /etc/ssh_config</pre>
  
- http://www.tortoisecvs.org/
+
* This will open the ssh configuration file for editing.
 +
* Go to the line which says ''# IdentityFile ~/.ssh/id_rsa''. Immediately after this line, add another line: ''# IdentityFile ~/.ssh/jmillers_key_for_brodylab''.
 +
(Remember that ''jmillers_key_for_brodylab'' should be replaced by your private key file name)
 +
* Save the file and exit.
  
- http://www.wincvs.org/
 
  
* Make sure that the directory that the "cvs" executable is in is in the system path once the program is installed, using the same procedure as above for PuTTY. It may automatically be placed there for you.
+
==='''Step 2''': Send us the public key so that we can grant you access to our server.===
  
 +
==== Windows ====
  
 +
Send us the .pub key file you saved using PuTTY in Step 1. Also, if you wish, you can send us a desired username for you on our Server.
  
=='''Step 6''': Configure your system to use your saved PuTTY session for CVS.==
+
==== Mac ====
  
The *easiest* way to instruct all cvs clients to use your saved PuTTY session is to define the environment variables CVS_RSH and CVSROOT.  
+
Send us the .pub key file you generated using ''ssh-keygen'' command in Terminal in Step 1. Also, send us the same username that you used on your Mac while generating the public-private key pair. We will need the same username to create a working login for you on our server. For example, in Step 1, we gave an example of the keys being generated under the username 'jmiller'.  
  
CVS clients will check these variables to determine what connections to open.
 
If you need to connect to other repositories for other applications, please see this footnote* on how CVS selects a connection.
 
  
 +
Our contact email is '''brodyadmin@princeton.edu'''. We will respond when your key is ready to be used to login to our servers.
  
To define these system variables:
 
  
- Click Start, Control Panel, System.
+
==='''Step 3''': Check if you are able to connect to our server ===
- Choose the Advanced tab and press the Environment Variables button at the bottom.
 
  
- In the lower section, click New.
+
==== Windows ====
- As the variable name,  enter:  CVSROOT
 
- As the variable value, enter:  <username>@<puttysession>:/cvs
 
    where <puttysession> is the name you gave the putty session we defined above and
 
    <username> is the username you used for the autologin setting in PuTTY
 
    (/cvs is the directory the repository is in on our server.)
 
- Click OK.
 
  
- Click New again (lower section) to enter a second system variable.
+
* Open the PuTTY Configuration window from Start->Programs->PuTTy
- As the variable name,  enter:  CVS_RSH
 
- As the variable value, enter the path of the executable plink file:  <PuTTYdirectory>\plink.exe
 
    where <PuTTYdirectory> is the directory in which you have installed the putty executables.
 
    If you added that directory to the system path, you can just type:  plink.exe
 
- Click OK.
 
  
Note that environment variables are loaded for a shell/program when it starts, so you'll have to e.g. open a new command prompt (or close and reopen WinCVS) for these variables to be usable there.
+
* In the '''''Sessions''''' option group (initially displayed):
 +
** Enter the following Host Name:  brodylab.princeton.edu
 +
** Select SSH as the connection type (Port should be set to 22)
  
At this point, if your username and key are confirmed with us, you should be good to go, with whatever cvs client you use, on the command line, through explorer, or in a big, ugly GUI. :D
+
* In the '''''Connection: Data''''' options subgroup (in the tree on the left):
 +
** Type in the username you received from us in the Auto-login username field.
  
=='''Step 7''': Checkout the ExperPort project.==
+
* In the '''''Connection: SSH''''' options subgroup (in the tree on the left):
 +
** Select "2" as your Preferred SSH protocol version.
  
*Pick or create a working directory in which to house the ExperPort project directory. We use C:\ratter.
+
* In the '''''Connection: SSH: Auth''''' options subgroup (in the tree on the left):
 +
** Enter the location of the private key you created (whose corresponding public key you sent to us).
  
How to check out the ExperPort project using a GUI varies slightly based on your cvs software (though it should be straightforward); however, you can always just use the command line.
+
* Back in the '''''Sessions''''' options group (top of the tree on the left):
 +
** Choose a name for the session we've created (like brodylab) in the edit field below the text "Saved Sessions". DO NOT USE SPACES OR SPECIAL CHARACTERS; other programs may not treat them properly.
 +
** Click Save.
  
Command line instructions:
+
Now your connection is set up and you can '''double-click''' it in the list of sessions to test it.
*Click the Start button, then click Run, then type    cmd  in the dialog box and hit enter.
 
*cd to the directory created (e.g. cd c:\ratter)
 
*Type:  cvs checkout ExperPort
 
  
 +
==== Mac ====
  
((Todo: add troubleshooting for the potential problems at this stage.))
+
Open the terminal and type the following command:
  
 +
<pre>ssh <username>@brodylab.princeton.edu</pre>
  
 +
where <username> is the name that you sent us to create a login for you on our server.
  
  
=='''Step 8''': Run ExperPort!==
+
'''''Notes:'''''
  
See the '''[[Startup Guide]]'''.
+
* If you haven't confirmed your key with us yet, login will ask for a password (and the Terminal or PuTTY may report that your key has been rejected by the server).
 +
* If you fail to connect repeatedly, your IP will be banned for 10 minutes.
  
  
 +
==='''Step 4''': Download (or checkout) ExperPort===
  
 +
==== Windows ====
  
==CVS Notes==
+
If you are using Tortoise SVN, as we recommended, do the following to download the ExperPort software from our servers:
  
'''Footnote''' on how CVS selects a connection:
+
* Run Pageant from Start->Programs->Pageant. It starts running and appears as a small icon in the bottom-right corner of your desktop.
  
There are several ways to tell CVS what connection to open, and the order will be important to you if you intend to connect to other cvs repositories, too:
+
* Right-Click on the running Pageant and add the private key you generated (whose public key you sent us) to the Pageant.
  
'''1-''' The -d argument in a cvs command (e.g. cvs -d :ext:user@server.edu:/repository_dir add somefile.txt), if specified, always determines the connection.
+
(Remember: Pageant should always be running with your private key added to it, if you want to checkout any thing from the server using an svn client)
  
'''2-''' If there is no -d flag, but there is a "CVS" directory in the directory cvs is called from (i.e. if you are inside a project you've checked out with cvs and type, for example, cvs update), the same connection is used that was used to check out the project.
+
* Open "My Computer" and browse to any directory. (say My Documents)
  
'''3-''' If there is no -d argument and you're not in a CVS working directory, the variables we defined (CVS_RSH and CVSROOT) are used.
+
* Right click and select "SVN Checkout". A window titled "Checkout" pops up. Type the following command in the box below "URL of repository" to download ExperPort:
  
 +
<pre>svn+ssh://<username>@brodylab.princeton.edu/chroot/ExperPort/trunk ExperPort</pre>
  
This means:
+
* The following command is to download the existing Protocols:
  
'''A-''' Technically, you only *need* to specify the cvs repository for the initial checkout.
+
<pre>svn+ssh://<username>@brodylab.princeton.edu/chroot/svn/trunk Protocols</pre>
  
'''B-''' Specifying CVS_RSH and CVSROOT won't affect projects you've already checked out by any other method.
+
==== Mac ====
  
Both A and B are because any commands you enter from inside a checked-out project's directories will already know what connection to use.
+
* Open Terminal window. Change to a directory of your choice where you want to download the files.
 +
* Type the following command to download ExperPort:
 +
<pre>svn checkout svn+ssh://<username>@brodylab.princeton.edu/chroot/ExperPort/trunk ExperPort</pre>
 +
* Type the following command to download Protocols:
 +
<pre>svn checkout svn+ssh://<username>@brodylab.princeton.edu/chroot/svn/trunk Protocols</pre>

Revision as of 22:03, 12 November 2010

You need two pieces of code:

  1. the RTLinux-side code (where the State Machine interpreter lives and interacts with the physical box).
  2. the Matlab-side code (where you write your trial-to-trial control software, known as a "Protocol," and from where you control the State Machine.


Initial Requirements

Before, we begin let us make sure we have the following

Terminal or Shell

Windows

On Windows, download and install putty from here which will serve as a Terminal or Shell. (Recommended: Install putty using the Windows Installer because it includes everything we would need now or in future: putty, puttygen, pageant etc.)

Mac

Mac already provides a built-in application called Terminal. It serves as the Terminal or Shell.

SVN Client

Windows

The most popular SVN Client for Windows is TortoiseSVN. Download it here and install.

Mac

SVN Client for Mac is included with the Developer's Tools. So, install Developer's Tools completely that come with your Mac OS X Installation CD/DVD, if you haven't done it yet. Insert the CD/DVD and the option to install Developer's Tools will come up. Then proceed with on-screen instructions.



Installation Guide for Beginners who want to first simply learn to use the system

RTLinux-Side

Emulator

For people that are just starting up, you'll most likely want to download the RTLinux-side code in its Emulator form. The Emulator pretends that it is an RTLinux machine with a physical behavior box, but just runs on your laptop. The Emulator shares most of its source code with the actual RT Linux source code. So you can learn to use and test your software without need of an extra CPU or a behavior box. It is thus a good place to start and learn to write protocols, interact with the state machine, and so on: you don't need an RT Linux machine for this, you just need your laptop. Instead of physical pokes, the Emulator GUI provides you with buttons that you click on with your mouse.

(Note: One currently very confusing thing about the Emulator's graphical interface: Ch. 00 is the Center poke; Ch. 01 is the Left poke, and Ch. 02 is the right poke. That is, they are ordered C,L,R, instead of L,C,R. We'll get around to changing that at some point.)

Windows

The latest emulator executable for Windows is ready for you to download and use right-away. Download the zip file here. Unzip it and double-click on FSMEmulator.exe to launch the emulator. (Tip: On Windows Vista and higher, right-click on FSMEmulator.exe and select "Run as Administrator" to launch the emulator.)

Mac

The latest emulator for Mac is not yet available in executable form (We are working on it). So, until we are done with it, follow these steps:

  • Download and install Qt4 or higher (framework only) from here.
  • Download the RTLinux Source code by typing the following command in your Terminal:
$ svn checkout http://rt-fsm.googlecode.com/svn/trunk/ rt-fsm-read-only

(By doing the above, a new directory name 'rt-fsm-read-only' will be created in the current location and all the RTLinux-Source code will be downloaded into it.)

  • Stay in the terminal, and type the following commands
$ cd rt-fsm-read-only/emulator
$ ./compile.sh clean
$ ./compile.sh
  • The compilation might take a few minutes. After it is done, you can exit the terminal. The emulator should now be available at rt-fsm-read-only/emulator/osx-x86/FSMEmulator.app. Launch the emulator by double-clicking on it.


Physical Machine

Alternatively, if you want to use the RTLinux-Side code on your physical RTLinux machine, download it using SVN Client from here, and follow the instructions (available in a file named INSTALL_STEP_BY_STEP in the downloaded directory) on how to install source code on the actual RTLinux machine.


MATLAB-Side

The Matlab-side code is the same whether you are interacting with an RTLinux Machine or Emulator on your laptop. Download the code in zip format (for Windows users) or tarred/gzipped format (for Mac Users). Unzip it and read the Startup Guide to start using it.



Installation Guide for Advanced Users (core code and behavioral protocol developers)

RTLinux-Side

On your RTLinux machine, you will need RTLinux Source Code which can be downloaded here or you can choose to use the emulator (read beginner's instructions above).


MATLAB-Side

As a developer, downloading ExperPort (current name of the Matlab-side behavioral control project) from SVN repository, and keeping it up to date is your best option. Assuming you took care of the Initial Requirements (above), follow these simple steps to download ExperPort from SVN repositories:

Step 1: Generate public-private key pair

Windows

  • Open PuTTYgen from Start->Programs->PuTTy
  • Select the SSH-2 DSA radio button at the bottom of the PuTTY Key Generator window.
  • Press the Generate button.
  • Add whatever short key comment you like.
  • You may select a passphrase or elect not to. It is slightly easier not to use one.
  • Pick a nice safe place (Not in code or data directories!) to save both your public and private keys-- that is, you have to click on both "Save public key" and "Save private key."
  • For example, you can save your private key as 'jmillers_key_for_brodylab.ppk' and public key as 'jmillers_key_for_brodylab.pub'.

Mac

  • Open the Terminal window.
  • Make sure you are in your user directory. Lets say /Users/jmiller.
  • Type the following command: ssh-keygen
  • While it is generating the keys, it will ask for a name for your key. Give a name to your key. Fox example let's say 'jmillers_key_for_brodylab'.
  • It will also ask you to type a passphrase. You may enter a passphrase or elect not to. It is slightly easier not to use one.
  • Two keys will be created now in /Users/jmiller directory. One is 'jmillers_key_for_brodylab' (this is the private key) and other is 'jmillers_key_for_brodylab.pub' (this is the public key).
  • Create a directory named '.ssh' (without the quotes), place your private key in it and modify the permissions of .ssh directory and this key as shown below:
$ cd /Users/jmiller
$ mkdir .ssh
$ chmod 700 .ssh
$ cp jmillers_key_for_brodylab .ssh/
$ cd .ssh
$ chmod 600 jmillers_key_for_brodylab
  • Open ssh configuration file for editing as follows:
$ sudo su
Password: <Enter your password here>
$ nano /etc/ssh_config
  • This will open the ssh configuration file for editing.
  • Go to the line which says # IdentityFile ~/.ssh/id_rsa. Immediately after this line, add another line: # IdentityFile ~/.ssh/jmillers_key_for_brodylab.

(Remember that jmillers_key_for_brodylab should be replaced by your private key file name)

  • Save the file and exit.


Step 2: Send us the public key so that we can grant you access to our server.

Windows

Send us the .pub key file you saved using PuTTY in Step 1. Also, if you wish, you can send us a desired username for you on our Server.

Mac

Send us the .pub key file you generated using ssh-keygen command in Terminal in Step 1. Also, send us the same username that you used on your Mac while generating the public-private key pair. We will need the same username to create a working login for you on our server. For example, in Step 1, we gave an example of the keys being generated under the username 'jmiller'.


Our contact email is brodyadmin@princeton.edu. We will respond when your key is ready to be used to login to our servers.


Step 3: Check if you are able to connect to our server

Windows

  • Open the PuTTY Configuration window from Start->Programs->PuTTy
  • In the Sessions option group (initially displayed):
    • Enter the following Host Name: brodylab.princeton.edu
    • Select SSH as the connection type (Port should be set to 22)
  • In the Connection: Data options subgroup (in the tree on the left):
    • Type in the username you received from us in the Auto-login username field.
  • In the Connection: SSH options subgroup (in the tree on the left):
    • Select "2" as your Preferred SSH protocol version.
  • In the Connection: SSH: Auth options subgroup (in the tree on the left):
    • Enter the location of the private key you created (whose corresponding public key you sent to us).
  • Back in the Sessions options group (top of the tree on the left):
    • Choose a name for the session we've created (like brodylab) in the edit field below the text "Saved Sessions". DO NOT USE SPACES OR SPECIAL CHARACTERS; other programs may not treat them properly.
    • Click Save.

Now your connection is set up and you can double-click it in the list of sessions to test it.

Mac

Open the terminal and type the following command:

ssh <username>@brodylab.princeton.edu

where <username> is the name that you sent us to create a login for you on our server.


Notes:

  • If you haven't confirmed your key with us yet, login will ask for a password (and the Terminal or PuTTY may report that your key has been rejected by the server).
  • If you fail to connect repeatedly, your IP will be banned for 10 minutes.


Step 4: Download (or checkout) ExperPort

Windows

If you are using Tortoise SVN, as we recommended, do the following to download the ExperPort software from our servers:

  • Run Pageant from Start->Programs->Pageant. It starts running and appears as a small icon in the bottom-right corner of your desktop.
  • Right-Click on the running Pageant and add the private key you generated (whose public key you sent us) to the Pageant.

(Remember: Pageant should always be running with your private key added to it, if you want to checkout any thing from the server using an svn client)

  • Open "My Computer" and browse to any directory. (say My Documents)
  • Right click and select "SVN Checkout". A window titled "Checkout" pops up. Type the following command in the box below "URL of repository" to download ExperPort:
svn+ssh://<username>@brodylab.princeton.edu/chroot/ExperPort/trunk ExperPort
  • The following command is to download the existing Protocols:
svn+ssh://<username>@brodylab.princeton.edu/chroot/svn/trunk Protocols

Mac

  • Open Terminal window. Change to a directory of your choice where you want to download the files.
  • Type the following command to download ExperPort:
svn checkout svn+ssh://<username>@brodylab.princeton.edu/chroot/ExperPort/trunk ExperPort
  • Type the following command to download Protocols:
svn checkout svn+ssh://<username>@brodylab.princeton.edu/chroot/svn/trunk Protocols