HMTsu

1. License
----------
Copyright (c) 2013 Lcferrum

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

2. About
--------
HMTsu (pronounced  'harmattan-su') is a gksu-like tool for N9 smartphone,
frontend to devel-su, sudo and ariadne. It provides graphical password prompt
and GUI to launch apps with root priveleges without the need to open terminal
and run mentioned tools directly.

3. Where to get
---------------
You can build .deb package by yourself (refer to 'Building' section) or 
download ready-made version from Sourceforge:

	https://sourceforge.net/projects/hmtsu/files/hmtsu/
	
Main project homepage is at GitHub:

	https://github.com/lcferrum/hmtsu

4. Usage
--------
After installing the .deb file on your device (don't forget to allow
installation from non-Store sources in the Settings) HMTsu will be available
right from application screen and from terminal (symlinks are added to 
/usr/bin/). 

If HMTsu is launched from application screen or command was not
given when launched from terminal - it will show a configuration GUI which
mirrors almost every CLI option. Also GUI provides application selection dialog
for the case when actual command is not known. If command was given when 
launching HMTsu - it will skip configuration GUI and go directly to password
prompt.

Please note that --print-pass option is a special case: it is not available
from configuration GUI and doesn't require command (but requires --description
or --message).

Usage (when launched from terminal): 
    hmtsu [-u <user>] [options] [<command>]  
    hmtsudo [-u <user>] [options] [<command>]  
    hmtadn [-u <user>] [options] [<command>]  
      
--help, -h    
    Display this help and exit.  
	
--version, -v    
    Output version information and exit.  

--verbosity-level <level>, -V <level>
    This option controls pop-up's verbosity and debug output availability. 
    Each level includes the previous levels as well.    
    LEVEL   DESCRIPTION    
    -----   --------------------------------------------------------- 
        0 - No pop-ups, only error dialogs and standard/error output.    
        1 - General informational pop-up messages.    
        2 - Error pop-up messages.    
        3 - Warning pop-up messages (default level).    
        4 - Debug output.  

--user <user>, -u <user>    
    Call <command> as the specified user (default: root).  
      
--preserve-env, -k    
    Try to preserve the current environments.  

--login, -l    
    Make this a login shell.  
      
--description <description|file>, -D <description|file>    
    Provide a descriptive name for the command to be used in the default
    message, making it nicer. You can also provide the absolute path for a    
    .desktop file. X-MeeGo-Logical-Id or Name keys will be used in this case.  

--message <message|file>, -m <message|file>    
    Replace the standard message shown to ask for password for the argument
    passed to the option. Only use this if --description does not suffice. You
    can also provide the absolute path for a .desktop file. Comment key will be
    used in this case.
	
--force-desktop, -f
    Extract command line, application icon and splash image from .desktop file
    provided in --description or --message.
    
--print-pass, -p    
    Ask HMTsu to print the password to stdout, just like ssh-askpass. Useful
    to use in scripts with programs that accept receiving the password on 
    stdin. HMTsu doesn't check password and user existence during this.  
      
--sudo-mode, -S    
    Make HMTsu use sudo (default mode for hmtsudo).  

--su-mode, -w    
    Make HMTsu use devel-su (default mode for hmtsu).  

--ariadne-mode, -a    
    Make HMTsu use ariadne (default mode for hmtadn).  
      
--    
    The -- option indicates that HMTsu should stop processing command line
    arguments.
	
5. Usage example
----------------                              
Example 1:
    hmtsu -u root -D "current processes" --ariadne-mode -- ps aux
	   
HMTsu will ask user to enter administrative password to run 'current 
processes'. Ariadne will be used to substitute user and run 'ps aux' command.

Example 2:
    hmtsu -fD /usr/share/applications/SomeProgram.desktop
	   
HMTsu will ask user to enter administrative password to run application (app
name will be taken from Name key). Devel-su will be used to substitute user and
run command from Exec key as root. Program icon (and splash screen, if present)
will be displayed during launch.

6. Additional notes
-------------------
HMTsu won't ask for password (though GUI will be shown either way) if devel-su
is used and current user is root or if sudo is used and appropriate credentials
were cached. Credential caching for ariadne is not supported - it will be
forced to ask for password every time.

--force-desktop option causes HMTsu not only to use value of Exec key as
command line but also to parse invoker arguments (if present) to determine
actual command line and path to splash screen. It is still possible to pass
command line as argument to HMTsu while using --force-desktop option - in this
case external command line will override command line from .desktop file.

Some Harmattan apps may crash on exit if were launched with root privileges.
HMTsu will report this through warning pop-up message. If you acknowledged of
such behavior and don't want to see this pop-ups - set verbosity to level 2.

Pop-up messages use Harmattan notification mechanism. If HMTsu itself is run
under root - this pop-ups can cause segfaults (if no additional steps to
prevent this were taken). You can disable pop-ups altogether (error pop-up
messages will be redirected to stderr in this case) with verbosity set to
level 0.

Sudo (if not launched as login shell) and ariadne use exec internally to launch
commands. So in this case you can't use shell commands directly like with
devel-su.

There is also opensudo package for Harmattan - it provides similar aegised
privileges like ariadne, but functions like sudo. Sudo and opensudo packages
are mutually exclusive - you can't have both of them installed at the same
time. HMTsu doesn't distinguish opensudo from sudo and will use either of them
when in sudo mode.
	
7. Building
-----------
The easiest way to build HMTsu is by using MeeGo 1.2 Harmattan Platform SDK
provided by Nokia. Just make sure that you have installed Platform SDK
correctly, start scratchbox, select HARMATTAN_ARMEL target, switch to sources
directory and type:

	./prepare_for_scratchbox.sh release
	dpkg-buildpackage -rfakeroot

You can also use Qt Creator with Harmattan SDK to build HMTsu - just open
hmtsu.pro in Qt Creator, select Harmattan target, release translations and
run the project.