Intronet user's manual

Introduction

What is Intronet?

Intronet is a light weighted framework which allows user to work with remote Linux system and to do some administration tasks using web browser. It's fully usable in browsers at mobile devices such pda, modern cell phones, etc.

Intronet consists of simple and steady definated module system. It allows Intronet to be easily expanded or modified. Everybody can write their own module what they need from Intronet.

Intronet also provides easy access to other web applications (e.g. webmail, calendar, etc.) through its autologin feature. You can add a web application into your profile filling the login information. Next time Intronet will do the login process automatically and you can use several web applications easily and faster.

With all this you can have your pc easily accessible everywhere and everytime you need. You can access your documents, e-mails, administrate your system and much more.

How it works?

Intronet is runned as service and listen on defined port. It is written in Python programming language. It uses CherryPy module with http server to communicate with user and output is generated with Cheetah template engine.

Tell me more

When user logs in, an invisible shell is started at the background. All modules can access this shell, send it commands and parse an output through core modules of Intronet. So intronet simulates something like web-based ssh.

Licence

Intronet is distributed under the terms of the GNU General Public License.

Getting started

Requirements

Intronet can be run on Linux system and needs these applications to be installed (versions are the minimal required).

Python 2.5

http://www.python.org/
CherryPy 3

http://www.cherrypy.org/
Cheetah 2.0

http://www.cheetahtemplate.org/
pyopenssl 0.6

http://pyopenssl.sourceforge.net

only if you want to use SSL

Installation

No special installation is needed. Just extract files in directory where you want to have Intronet.

Running Intronet

Start intronet.py in directory where you installed Intronet. Intronet will listen on definated port (default is 8001).

System-wide

If you want to allow all users in system access to Intronet run it with root privileges.

Users have to use their system passwords in order to log into Intronet.

Single user

When using Intronet for only one user run Intronet with this user privileges.

You will be prompted to fill in the password on the first connection to Intronet.

Set your password as soon as possible after running Intronet to avoid security risks.

Configuration

Configuration file

Configuration file intronet.cfg is in root directory of Intronet. You can set port and some other things there.

Example: Setting port

server.socket_port = 8001

Example: Setting certificate for SSL

server.ssl_certificate = "server.crt"
server.ssl_private_key = "server.pem"

If you want to turn SSL off remove these two lines.

It is highly recommended to keep SSL turned on.

Also you have to generate your own SSL certificate because the one in distribution is public accessible and for another domain.

For easy SSL certificate generation you can use openssl.

Administration

After login into Intronet as Administrator (as root when Intronet is run system-wide or as normal user) there is an Administration link in the menu. You can allow to use another modules to other users of Intronet there.

Settings

In Settings section of Intronet you can add (or remove) various modules that were permitted in Administration into your profile and then they are accessible from the menu.

You can also add or remove an application into your profile.

Autologin feature

Only applications based on cookie authentication are supported.

If you want to use autologin feature application must be in the same domain as Intronet is run otherwise this feature will not work. Browser do not let Intronet to set cookies to another domain due to security. But if you have browser that do not have this security feature you can use autologin in applications on another domains.

This is the list of a few applications that were tested:

phpMyAdmin
Horde (escpecially IMP - mail client that supports POP3, IMAP and SMTP)
SquirrelMail

Using of Intronet - modules

With standard installation of Intronet these modules are available:

File system

File manager that supports basic file operation such as copying, moving, uploading, finding files etc.
Shell

Basic HTML simulation of ssh.
File editor

Standard file editor for basic editing. It is usable for editing large files and provides standard functions find and find & replace.

File system module

Provides standard file system operations. Directory is listed with standard ls command and output is shown.

You can browse directory or download files with clicking on them. You have also option to view files online or edit them in text editor.

Copying, moving, deletion

You can select files and directories using checkboxs in front of them and then use some operation upon the selection. If you want to delete some files, just select them and click on delete button.

If you click on copy or cut, files are stored into “clipboard” and new button Paste files appears. It copies or moves files in “clipboard” into directory you are actually in.

Changing permissions, owner and group

If you click on permissions in the list of files, you can change file permissions and if you are root, owner and group as well.

When changing owner and group you can change only one of them. You can choose from changing text value or numeric id value.

Shell module

This module provides a basic simulation of a shell prompt. There was much intetions to make it as interactive and secure as possible.

Your commands are parsed with unix bourne shell (sh). When you submit a command it has a little time to execution and returning some output. If this time limit is exceeded, partial or none output is returned. You have to press Get next data then. There is also a timelimit to complete data transfer from command (currently set to 5 seconds). After that limit output is sent to user. You can press Get next data button for next output as well.

Editor module

This module handles basic file editing. It offers find and find & replace functions. File is devided into smaller pieces and paged in several pages in order to achieve smaller traffic. You edit this pieces separately.

Find

A search pattern will be searched from actual position in the file. It is found the first piece with an occurence of the pattern and is highlighted and shown. You can press Next button to search next pieces of the file, Previous for one previous search position or Cancel to perform new search.

Search is case-sensitive.

Find & Replace

You can choose from Find & Replace which asks before every replacement or Find & Replace all which replaces all occurences of search pattern in the file.

Writing modules

Advanced users can write their own modules into Intronet if they need some extra functions and want them to be easily accessible. For example someone would want one-click restarting daemons function, viewing of logs or other stuffs.

Everything you need is knowledge of Python programming and a little of Cheetah template system. But don't worry everything is really easy and after reading of code of some standard module and this section you will be able to write your own :).

Example of creating new `Mymodule`

First you need to create a new Cheetah template file in tmpl directory.

Example: mymodule.tmpl

<h1>My module</h1>
This is only test!
And this is test variable: $foo<br />
<a href="index">First page</a> | <a href="bar">'Bar' page</a><br />
Your username is: $user

Than compile this template with cheetah:

$ /usr/bin/cheetah c tmpl/mymodule.tmpl --odir modules/templates/

Then create file in modules directory called mymodule.py and start editing it in your favourite editor:

Example: mymodule.py

# first we import module class definition
import module
# next import template
from templates.mymodule import mymodule

# some other imports ...

# start with definition of our new module
class Module(module.Module):
    # url must be same as name of the file.
    url = 'mymodule'
    name = 'MyModule Name'
    # true if module is accessible only for logged users otherwise
    # module can be access by everyone on http://intronet-adress/mymodule/
    secured = True
    # template have to point to template class
    template = mymodule

    # create index page
    def index(self):
        # this checks security (if user is properly logged in and return user
        # and template object. It should be at every accessible function and
        # in every function we need to work with template
        user, template = self.CheckModule()
        # fill foo variable in template
        template.foo = 'We are at index page'
        # fill template variable user with actual username
        template.user = user.username
        # and return output through module class
        return module.Module.index(self, template)

    # this is cherrypy stuff to tell that index is accessible
    index.exposed = True

    # create another page
    def bar(self):
        # check the security as described before
        user, template = self.CheckModule()
        # change template variable
        template.foo = 'We are at page <strong>bar</strong>'
        return module.Module.index(self, template)

    bar.exposed = True

You can check your module that it could be added into Intronet now.

Now we can do something more advanced. First add a simple form into template:

Example: mymodule.tmpl

<h1>My module</h1>
This is only test!
And this is test variable: $foo<br />
<a href="index">First page</a> | <a href="bar">'Bar' page</a><br />
Your username is: $user<br />
Your saved value: $test<br />
<br />
<form action="set" method="post">
  Enter some value: <input type="text" name="test" /> <input type="submit" value="Save" />
</form>

Don't forget to recompile the template with cheetah command.

$ /usr/bin/cheetah c tmpl/mymodule.tmpl --odir modules/templates/

And now create new function set that saves our given value.

Example: mymodule.py

# first we import module class definition
import module
# next import template
from templates.mymodule import mymodule

# some other imports ...

# start with definition of our new module
class Module(module.Module):
    # url must be same as name of the file.
    url = 'mymodule'
    name = 'MyModule Name'
    # true if module is accessible only for logged users otherwise
    # module can be access by everyone on http://intronet-adress/mymodule/
    secured = True
    # template have to point to template class
    template = mymodule
    # here we can set some template vars to their default values
    template.test = 'No value'

    # create index page
    def index(self):
        # this checks security (if user is properly logged in and return user
        # and template object. It should be at every accessible function and
        # in every function we need to work with template
        user, template = self.CheckModule()
        # fill foo variable in template
        template.foo = 'We are at index page'
        # fill template variable user with actual username
        template.user = user.username
        # and return output through module class
        return module.Module.index(self, template)

    # this is cherrypy stuff to tell that index is accessible
    index.exposed = True

    # create another page
    def bar(self):
        # check the security as described before
        user, template = self.CheckModule()
        # change template variable
        template.foo = 'We are at page <strong>bar</strong>'
        return module.Module.index(self, template)

    bar.exposed = True

    # form items are automatically parsed into function arguments thanks to
    # cherrypy.
    def set(self, test):
        # get template object and check security
        user, template = self.CheckModule()
        # set our value
        template.test = test
        return module.Module.index(self, template)

    set.exposed = True

Now you can see you can set any value into a template variable with this example. This variable is pernament to session; it means when you go into another module (e.g. File system) and then back value of the variable will be same as before. So you see a template objects are pernament per users.

Running commands

Easy access to shell and running commands is the most advantage of Intronet. For this you can use core module named modules.core.command. It offers two functions Command and ExecReturn. They are nearly identical, both run a command on system but result is different. The first return output of the command and the second return status of the command.

Command function

def Command(command, shell, history = True, timeout = 5, noprompt = False, check = False, wait=1, kill=False)

Runs command in shell. In all cases (in bundled modules) this shell is user's shell (user.shell). Returns 2-tuple object (command output, return code of shell object).

command - A command to run.
shell - Shell object of the shell where command should be run.
history - Whether command output should be added into shell's history.
timeout - Overall timeout to transfer output.
noprompt - Whether an ending prompt should be replaced.
check - Function return 3-tuple object with adding of status code of command.
wait - Waiting time in second for command to generate output. Default is 1. In command with high time consuming (e.g. find) this should be larger (in find function in file system module this is set to 30)
kill - Whether the command should be killed after some error or when timed out

Many useful things and tricks when creating modules can be found in standard modules in Intronet such as in editor module. It is not so hard and time-consuming to write your own module.

Bundled editor have less than 500 lines.

Intronet user's manual

Introduction

What is Intronet?

How it works?

Tell me more

Licence

Getting started

Requirements

Installation

Running Intronet

System-wide

Single user

Configuration

Configuration file

Administration

Settings

Autologin feature

Using of Intronet - modules

File system module

Copying, moving, deletion

Changing permissions, owner and group

Shell module

Editor module

Find

Find & Replace

Writing modules

Example of creating new Mymodule

Running commands

Command function

Author

Example of creating new `Mymodule`