Gnome xsu documentation

# Documentation for Gnome Xsu

- ### Introduction

          xsu Is an interface for the command `su - username -c command` in Gnome. When
          the user executes xsu, he will be prompted for a command, a username and a
          password. If the username and password are correct xsu will execute the command
          as the entered user. So if the username was root, then the command will be
          executed as root.

          Of course it's also possible to predefine the username and the command by
          using the [-u,--username] and [-c,--command] arguments at the command line
          of xsu. This can be very useful when using xsu in for example gmenu or the
          panel.

- ### Security

          Gnome Xsu 0.2.0 uses the standard su binary to gain it's root access. This
          way, all security issues should be solved.

          The security of all older xsu versions was very bad. With xsu version 0.1.0
          I introduced the use of a pipe to a secured non-Gnome SUID application. This
          has been replaced with a special type of pipe to the standard su application.
          For example the one from GNU sh-utils can be used with Gnome Xsu.

- ### Known issues

          Gnome Xsu uses the Unix 'su' execute the command. This means that your
          DISPLAY environment variable of the user must be set correctly. You can
          put for example export DISPLAY=:0 in the file /etc/profile (bash).
          You can also use the option --set-display which will set the DISPLAY environment
          variable to ":0" before starting the command.

- ### Installation

          ! You need the Gnome (And GTK+, GDK) development packages (Gnome libs)

          Example (RedHat Linux)
          ./configure
          make
          make install

        Special options for ./configure

          usage: configure [--option=value]

              Help:
      	 --help				print this message

              Directory and file names:
              --man-base=PATH			Set path to man pages [/usr/share/man]
              --doc-path=PATH			Set path for documentation [/usr/share/doc]
              --compiler=PATH			Set compiler [cc]
              --gnome-config-prefix=PATH	Where to find gnome-config []
      	--prefix=PATH			Installation base
              --su-pwd-out=STRVALUE           Set what su outputs while waiting for password.
                                              Gnome Xsu will wait for this string to send the
                                              password through the faked terminal. So this string
                                              MUST be correct ! (test with "su - root -c test")
                                              [Password: ]
              --max-su-delay=INTVALUE         Delay before su fails [30000]
              --debug                         Enables debugging mode (only for developpers)

       Uninstallation (dont remove the Makefile nor do make distclean)
          make uninstall

       Doing a distclean
          make distclean

       For distrubutions which do not use a standard Unix su command
          Argh, get yourself GNU sh-utils. Oh well, in case you don't want to install
          another su-package, you can try the configuration option --su-pwd-out.
          Basicly it comes to this : Gnome Xsu will wait until the faked zvt terminal
          where su has been executed returns "Password: " before it sends the password
          which you typed at the password textbox to the terminal. Using this
          configuration option, you can change that string. However, I still recommend
          installing GNU sh-utils. Gnome Xsu has only been tested with the GNU sh-utils
          package.

- ### Little manual

          - Commandline parameters for xsu
              * [-u|--username] "username"            Sets the username.
              * [-c|--command] "command line"         Sets the command.
              * [-m|--message] "Message^line"         Sets the message.
      	* [-t|--title] "Window title"           Sets the window title.
      	* [-i|--icon] "pixmap file"		Loads another icon.
      	* [-e|--hide]				Hides the username.
      	* [-a|--set-display] "hostname:port"    Sets the DISPLAY
                                                      environment variable
                                                      to :0 before starting
                                                      the command if no 2e
                                                      argument is given. Else
                                                      use the Xserver at
                                                      hostname:p
              * [-d|--unadaptable]                    Disables the username
                                                      and command textboxes
                                                      if possible.
              * [-h|--help]                           Displays help.

              ps. When using -m or --message you can use the character ^
              in your message if you want to use a new line, and the character
              ~ if you want to use a tabulation. If no message is set, then
              the default message will be used :

                  The action you requested requires root
                  priveleges.
                  Please enter the correct password for it
                  below and press [Return] or click OK.
              Example :

                  xsu --message "The action you requested requires root^priveleges.^Please enter the correct password for it^below and press [Return] or click OK."

          - Using xsu in gmenu (Menu Editor)
              At the "Command:" textbox just use for example
              xsu -c "The command line" -u "root" -m "Enter the root password^please."

              * Examples :
                  Command: xsu -c "gmenu" -u "root" -m "To start the Menu Editor^you have to enter^the root password^here."
      	    Command: xsu --title "" -c DrakConf -u root -d -e -m "In order to run \"DrakConf\" as root.^Additional information is required."
      	    Command: xsu --title "" -c xterm -u root -d -e -m "In order to run \"xterm\" as root.^Additional information is required." -i "/usr/share/pixmaps/gnome-hint.png"

- ### Using xsu in gmenu

- ### xsu - this example

      xsu --command "gmenu" --username "root" --message "For the Menu Editor you need root access.^Enter the root password Below."

- ### Another example

      xsu --title "" -c DrakConf -u root -d -e -m "In order to run \"DrakConf\" as root.^Additional information is required."

- ### Last example

      xsu --title "" -c xterm -u root -d -e -m "In order to run \"xterm\" as root.^Additional information is required."
      	-i "/usr/share/pixmaps/gnome-hint.png"

- ### Others - final words

  - Tested and compiled on
    - Development system
      - Mandrake 8.0
        - gcc update
        - Ximian Gnome update
        - Gnome-libs 1.2.13
      - RedHat 7.0
        - gcc update
        - Ximian Gnome update
        - Gnome-libs 1.2.11
    - RedHat 6.0, Gnome-libs 1.0.8
    - RedHat 6.1, Gnome-libs 1.0.40
    - RedHat 6.2, Gnome-libs 1.?.?
    - RedHat 7.0, Gnome-libs 1.2.4
    - Debian
      - potato, woody
      - Ximian Gnome update
      - Gnome-libs 1.2.11
    - FreeBSD 4.1.1, Gnome-libs 1.2.4

  - Latest version and reference
    - Projects homepage
    - http://www.freax.eu.org
    - Files and older releases
    - The sourceforge xsu-site
    - The freshmeat record of xsu