Belier
======

What's for ?
------------
Belier allows opening a shell or executing a command on a remote computer through a SSH connection. The main feature of Belier is its ability to cross several intermediate computers before realizing the job.

- Belier reaches the final computer through intermediate machines.
- You can execute commands with any account available on the remote computer.
- It is possible to switch account on intermediate computers before accessing the final computer.
- You can open a data tunnel through every host you cross to the final host.
- Belier generates one script for each final computer to reach.

License
-------
GPLv3 and more

What you need before installing Belier
--------------------------------------
- Python >= 2.4
- Expect >= 5.42.1

Debian :
-------------------------------
# apt-get install python expect
-------------------------------

Installation
------------
From sources
~~~~~~~~~~~~
-----------------------
$ tar zxvf
$ cd belier-1.1
$ su -
# python setup.py install
-------------------------

Easy_install
~~~~~~~~~~~~
---------------------
# easy_install belier
---------------------

Source code
-----------

----------------------------------------
$ git clone git://git.ohmytux.com/belier
----------------------------------------

Howtos
------
Information file syntax
~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------------
[user@]host[:port] [pass|user [pass]] [-c|-t|-ot]
-------------------------------------------------

Open a remote shell as root
~~~~~~~~~~~~~~~~~~~~~~~~~~~

We first write a file which defines information to access the final computer :
-------------------------------
admin@host Ic4r3 root jkw!po12;
-------------------------------

Belier generates the script :
---------------------
$ bel --entree=ordres
$ ls
ordres host.sh
----------------

Execution of the script (only the script is executed here, the other lines are self-generated) :
-------------------------------
user@localhost:~$ ./host.sh
spawn ssh host
admin@host's password:
admin@host:~$ su - root
Password:
root@host:~#
------------

Let's be more verbose about this example :

. We write a file with the mandatory information to connect the remote computer. The first field is composed by a login followed by '@' and the hostname (could be an ip address). You can omit the login and in this case, the actual login of your shell session will be used.
. The second field is a password to access the remote computer. It could be omitted if you exchanged ssh keys between the both computers.
. The third field is the login you want to switch to after beeing connected to the remote computer. It could be omitted if you don't need to switch.
. The fourth and last field is the required password for the user switching. Could be omitted too.
. You generate the connection script. You could use standard input but in our example we use --entree option to pinpoint the information file.
. You launch the script and you reach the final computer.

Open a remote shell with several intermediate computers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We first write a file which defines information to access the final host:
----------------------------
middlehost1 admin azer0;lp!Z
admin@middlehost2
admin@lasthost root jkw!po12;
-----------------------------

Belier generates the script:
---------------------
$ bel --entree=ordres
$ ls
ordres lasthost.sh
--------------------

Execution of the script (only the script is executed here, the other lines are self-generated):
-------------------------------
user@localhost:~$ ./lasthost.sh
spawn ssh middlehost1
user@middlehost1's password:
user@middlehost1:~$ su - admin
Password:
admin@middlehost1:~$ ssh admin@middlehost2
admin@middlehost2:~$ ssh admin@lasthost
admin@lasthost's password:
admin@lasthost:~$ su - root
Password:
root@lasthost:~#
----------------

Let's be more verbose about this example:

. The first line of the information file defines the first intermediate computer to reach. On this one we also define a user switch.
. The second line defines the second intermediate computer.
. The third line defines the final computer. On this computer we switch to root.
. You generate the connection script. You could use standard input but in our example we use --entree option to pinpoint the information file.
. You launch the script and you reach the final computer.

Execute a command on a remote computer as root
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We first write a file which defines information to access the final computer :
---------------------------
middlehost admin azer0;lp!Z
admin@lasthost root !ZuP3r; -c
df -h
-----

Belier generates the script :
---------------------
$ bel --entree=ordres
$ ls
ordres lasthost.sh
--------------------


Here is the output of the execution of the generated script :
-------------------------------
user@localhost:~$ ./lasthost.sh
spawn ssh middlehost
user@middlehost's password:
user@middlehost:~$ su - admin
Password:
admin@middlehost:~$ ssh admin@lasthost
admin@lasthost's password:
admin@lasthost:~$ su - root
Password:
root@lasthost:~# df -h
Sys. de fich.            Tail. Occ. Disp. %Occ. Monté sur
/dev/sda2             453G   61G  393G  14% /
varrun                2,0G  112K  2,0G   1% /var/run
varlock               2,0G     0  2,0G   0% /var/lock
udev                  2,0G   48K  2,0G   1% /dev
devshm                2,0G   24K  2,0G   1% /dev/shm
lrm                   2,0G   36M  1,9G   2% /lib/modules/2.6.24-21-generic/volatile
root@lasthost:~#
----------------

Let's be more verbose about this example :

. The first line of the information file defines the first intermediate computer to reach. On this one we also define a user switch.
. The second line defines the second intermediate computer.
. The third line defines the final computer. On this computer we switch to root.
. The fourth line defines the command we want to execute on the final computer.
. You generate the connection script. You could use standard input but in our example we use --entree option to pinpoint the information file.
. You launch the script and you reach the final computer.

Open a tunnel for data while connecting to a host
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We want to send a big file through several hosts. Copying it through the different hosts would be painful. Bélier offers an elegant solution to solve that case by opening on your source computer a network port sending data directly on the final machine you want to work on. By default this network port has the following number : 9999. Lets take the following order file :
------------------------
middlehost azer0;lp!z -t
admin@lasthost root jkw!po12;
-----------------------------

Belier generates the script :
---------------------
$ bel --entree=ordres
$ ls
ordres lasthost.sh
--------------------

Let's be more verbose about this example :

. That's a pretty common order file but you have at the end of the line the -t (for tunnel) option, which means you want a data tunnel to this machine.
. That's pretty much what you need. executing this script you'll connect and open a shell on the final host, as usual.
. But moreover, you have on your source host an open port allowing you to send data directly to the final host, using the scp command.

Execution of the script (only the script is executed here, the other lines are self-generated) :
-------------------------------
user@localhost:~$ ./lasthost.sh
user@middlehost's password:
user@middlehost:~$ ssh admin@lasthost
admin@lasthost:~$ su - root
password:
root@lasthost:~#
----------------
And now, leave this shell alone (don't close it or you'll lose the connection) and in a new one you'll use the scp command:
--------------------------------------------------------------
user@localhost:~$ scp -p 9999 my-big-file.iso root@127.0.0.1:~
root@127.0.0.1's password:
toto                                          100%   19     0.0kb/s   00:00
user@localhost:~$
-----------------
Your file has been successfully sent through every computers you usually have to cross! And you can use every command you want through this port, e.g ftp, rsync, whatever.

Open a tunnel for data with a specified port number while connecting to a host
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We want to send a big file through several hosts. Copying it through the different hosts would be painful. Bélier offers an elegant solution to solve that case by opening on your source computer a network port sending data directly on the final machine you want to work on. By default this network port has the following number : 9999. lets take the following order file :
-------------------------
middlehost azer0;lp!z -ot
8888 7777
admin@lasthost root jkw!po12;
-----------------------------

Belier generates the script :
---------------------
$ bel --entree=ordres
$ ls
ordres lasthost.sh
--------------------

Let's be more verbose about this example :

. That's a pretty common order file but you have at the end of the line the -ot (for tunnel options) option, which means you want a data tunnel to this machine.
. On the line following the one finishing by -ot you have to give to arguments: the local port you want to use and the remote port which is going to be opened.
. That's pretty much what you need. Executing this script you'll connect and open a shell on the final host, as usual.
. But moreover, you have on your source host an open port allowing you to send data directly to the final host, using the scp command.

execution of the script (only the script is executed here, the other lines are self-generated) :
-------------------------------
user@localhost:~$ ./lasthost.sh
user@middlehost's password:
user@middlehost:~$ ssh admin@lasthost
admin@lasthost:~$ su - root
password:
root@lasthost:~#
----------------
And now, leave this shell alone (don't close it or you'll lose the connection) and in a new one you'll use the scp command:
--------------------------------------------------------------
user@localhost:~$ scp -p 8888 my-big-file.iso root@127.0.0.1:~
root@127.0.0.1's password:
toto                                          100%   19     0.0kb/s   00:00
user@localhost:~$
-----------------
Your file has been successfully sent through every computer you usually have to cross! And you can use every command you want through the port you want to use, e.g ftp, rsync, whatever.

Useful to know with passwords in Belier
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If one of your passwords in the information file has a space in it, you need to wrap your password between quotation marks (character ") :
-----------------------------
admin@serveur "My Passw0rd  "
-----------------------------
If one of your passwords in the information file has a quotation mark in it, you need to put a backslash before (character \) :
-------------------------------
admin@serveur "My \"Pass word "
-------------------------------

Code quality
------------

Since the version 0.4, Belier has been tested (functional tests and regression tests). The code is parsed with Pylint. I also use a fuzzer called Fusil written by Victor Stinner. If you find a bug, please contact me.

Help / bugreports / feature requests
------------------------------------

- Users list - please suscribe to link:https://lists.sourceforge.net/mailman/listinfo/belier-users[the users mailing list].
- Developers list - please suscribe to link:https://lists.sourceforge.net/mailman/listinfo/belier-devel[the developers mailing list].

mailto:please-use-chaica@ohmytux.com['Carl Chenet aka Chaica']