********************************************************************************* Remote access and SSH ********************************************************************************* .. contents:: .. index:: remote access, ssh Remote logins -------------------------------------------------------------------------------------------- One of the most powerful features of GraphTerm is that basic inline image display and the notebook mode of GraphTerm work transparently across multiple SSH login boundaries. For example, in your GraphTerm window you can SSH to a remote computer and display a plot using python as follows:: local$ ssh user@remote_server remote$ python -i $GTERM_DIR/bin/gpylab.py >>> plot([1,2]) assuming the requisite files (see below) are present in the remote ``$GTERM_DIR/bin`` directory. You do not need to start a server on the remote computer because all communication occurs via the standard input/output of the remote python interpreter. In addition to displaying inline graphics, you can switch to notebook mode simply by typing *Shift-Enter*, just like you would on your local computer. (Note that saving/reading notebook files will take place on your current local directory, not on the remote system.) .. figure:: https://github.com/mitotic/graphterm/raw/master/doc-images/gt-ssh-plot.png :align: center :width: 90% :figwidth: 85% Remote installation -------------------------------------------------------------------------------------------- A minimalist remote installation of the GraphTerm environment requires copying seven files from the local ``$GTERM_DIR/bin`` directory to the directory ``~/graphterm/bin`` on the remote computer:: cd $GTERM_DIR/bin ssh user@remote_server mkdir -p graphterm/bin scp gterm.py gmatplot.py gpylab.py gpython gipython gframe gprofile user@remote_server:graphterm/bin Then, append the following line to your remote ``~/.profile`` or ``~/.bash_profile`` setup:: source ~/graphterm/bin/gprofile This adds ``~/graphterm/bin`` to your PATH variable, so that you can use commands like ``gpython`` for inline graphics display or ``gframe`` to display images or HTML pages, for example:: d3cloud file | gframe -f If you will be using R, you only need to copy the file ``gterm.R`` to the remote computer. For a more complete configuration, you can install GraphTerm in your home directory on the remote system, even if you never plan to run the server. Download the ``graphterm-version.tar.gz`` source tarball from https://pypi.python.org/pypi/graphterm, untar it and copy the subdirectory ``graphterm`` to ``~/graphterm``. (If you have root access, you can choose to install ``graphterm`` for all users on the remote computer using ``sudo pip install graphterm``.) .. index:: port forwarding Port forwarding -------------------------------------------------------------------------------------------- The more advanced features of GraphTerm are explicitly disabled from working across SSH login boundaries for security reasons. If you need the full suite of features, the most secure way to access the GraphTerm server running on a remote computer is to use SSH port forwarding. For example, if you are connecting to your work computer from home, and wish to connect to the GraphTerm server running as ``localhost`` on your work computer, use the command:: ssh -L 8901:localhost:8900 user@work-computer This will allow you to connect to ``http://localhost:8901`` on the browser on your home computer to access GraphTerm running on your work computer. If using *singleuser* authentication, copy the file ``~/.graphterm/_gterm_auth.txt`` from work to home as ``~/.graphterm/@server_name_gterm_auth.txt``, and use the ``gterm`` command:: gterm --server server_name --port 8900 http://localhost:8901 .. index:: reverse port forwarding Reverse port forwarding -------------------------------------------------------------------------------------------- A completely different approach is to use reverse forwarding. *Warning: If the remote computer is insecure, reverse forwarding should be used caution, and preferably with multiuser authentication.* Install GraphTerm on the remote computer and run the ``gtermhost`` program remotely to allow it to connect to the ``gtermserver`` running on your local computer using SSH reverse port forwarding, e.g.:: gauth remote1 | ssh user@remote1 'cat > ~/.graphterm/remote1_gterm_auth.txt' ssh -R 8799:localhost:8899 user@remote1 gtermhost --server_port 8799 --remote_port=8899 remote1 In this case, the remote computer will appear as another host on your local GraphTerm server. *Note: Do not do the following unless you trust the remote machine. A malicious remote program could execute commands on your local computer if it has access to the GraphTerm window.* If you do not wish to have a GraphTerm process running on the remote machine, you can still use many features though GraphTerm running on your local machine, because all communication takes place via the standard output of the remote process. One quick solution is use the *terminal/export environment* menu option to set the Bash shell environment variables on the remote computer. This will allow some, but not all, of GraphTerm's features to work on the remote session. A more permanent solution involves the following three steps: - Start the local GraphTerm server using the ``--lc_export=graphterm`` or ``--lc_export=telephone`` options, which export the GraphTerm environment via the ``LC_*`` environment variables which are typically transmitted across SSH tunnels. - Copy the ``$GTERM_DIR/bin`` directory to ``~/graphterm`` on the remote machine to allow the GraphTerm toolchain to be accessed: ``ssh user@remote_server mkdir graphterm`` ``scp -pr $GTERM_DIR/bin user@remote_server:graphterm`` Alternatively, you could simply install GraphTerm on the remote machine, even if you are never planning to start the server. - Append the file `$GTERM_DIR/bin/gprofile `_ to your ``.profile`` on the remote machine: ``cat gprofile >> ~/.profile`` Although this script can usually detect your GraphTerm installation directory, sometimes you may need to modify the last few lines to ensure that the GraphTerm toolchain is included in your ``PATH`` on the remote machine. This would allow commands like ``gls`` to work.