= Do not use Edit(GUI) button. =

[[TableOfContents(4)]]

Copyright 2007, 2008  Osamu Aoki GPL, (Please agree to GPL, GPL2, and any version of GPL which is compatible with DSFG if you update any part of wiki page)

I welcome your contributions to update the wiki pages. You must follow these rules:
 * Do not use Edit(GUI) button of MoinMoin.
 * You can update anytime for:
  * grammar errors
  * spelling errors
  * moved URL location
  * package name transition adjustment (emacs23 etc.)
  * clearly broken script.
 * Before updating real contents:
  * Read "[http://wiki.debian.org/DebianReference/Test Guide for contributing to Debian Reference]".

= The X window system =

The X window system on the Debian system is based on the source from [http://www.x.org/ X.Org]. As of March 2008, they are X11R7.1(etch), X11R7.2(lenny) and X11R7.3(sid).  

== Key packages ==

There are a few (meta)packages provided to ease installation.

|| List of key (meta)packages for X window. || 1 || 2 || 3 ||
|| '''(meta)package''' || '''popcon''' || '''size''' || '''description''' ||
|| {{{xorg}}} || - || - || This metapackage provides the X libraries, an X server, a set of fonts, and a group of basic X clients and utilities. ||
|| {{{xserver-xorg}}} || - || - || This package provides the full suits of the X server and its configuration. ||
|| {{{xbase-clients}}} || - || - || This package provides a miscellaneous assortment of the X clients. ||
|| {{{x11-common}}} || - || - || This package contains the filesystem infrastructure for the X window system. ||

For the basics of X, refer to {{{X}}}(7), [http://www.tldp.org/HOWTO/XWindow-User-HOWTO.html the LDP XWindow-User-HOWTO].  

== Setting up Desktop environment ==

You can setup KDE, GNOME, or Xfce environment from the {{{aptitude}}} under the task menu.

See [http://www.xwinman.org Window Managers for X] for the guide of the window managers and the desktop environments for the X window system.

== The server/client relationship ==

The X window system is activated as a combination of the server and client programs. The meaning for the words '''server''' and '''client''' with respect to the words '''local''' and '''remote''' requires attention here:

|| List of server/client terminology. || ||
|| '''type''' || '''description''' ||
|| '''X server''' || a program run on a '''local host''' connected to the user's display and input devices. ||
|| '''X client''' || a program run on a '''remote host''' that processes data and talks to the X server. ||
|| '''application server''' || a program run on a '''remote host''' that processes data and talks to the clients. ||
|| '''application client''' || a program run on a '''local host''' connected to the user's display and input devices. ||

== The X server ==

See {{{xorg}}}(1) for X server information.

=== The (re)configuration of the X server ===

To (re)configure an X server,

{{{
# dpkg-reconfigure --priority=low x11-common
# dpkg-reconfigure --priority=low xserver-xorg
}}}

will generate a new {{{/etc/X11/xorg.conf}}} file using {{{dexconf}}}(1). 

If you have manually edited this {{{/etc/X11/xorg.conf}}} file but would like it to be automatically updated again, run the following command:
{{{                                             
# sudo dpkg-reconfigure -phigh xserver-xorg                               
}}}

Please check your X configuration  with respect to the specification of your monitor carefully.  For the large high resolution CRT monitor, it is a good idea to set the refresh rate as high as your monitor can handle (85 Hz is great, 75 Hz is OK) to reduce flicker.  For the LCD monitor, slower standard refresh rate (60Hz) is usually fine due to its slow response.

(!) Be careful not to use too high refresh rate which may cause fatal hardware failure of your monitor system.

=== The fonts in the X window ===

The {{{defoma}}} package, which stands for "DEbian FOnt MAnager", provides a framework for automatic font configuration including X.

The {{{aptitude}}} will help you find required font easily 
 * by the short package list under "Packages which depend on defoma" under the {{{defoma}}} package list,
 * by the short package list under "Tasks" ->  "Localization",
 * by the filtered flat package list of font data with regex on debtag: "{{{~Gmade-of::data:font}}}",
 * by the filtered flat package list of the BDF (bitmap) font packages with regex on package name: "{{{~nxfonts-}}}", or
 * by the filtered flat package list of the TrueType (outline) font packages with regex on package name: "{{{~nttf-}}}".

The standard {{{xfs}}} in the X server works fine with TrueType fonts.

Since '''Free''' fonts are sometimes limited, installing or sharing some commercial TrueType fonts is an option for a Debian users.  In order to make this process easy for the user, some convenience packages have been created:
 * {{{ttf-commercial}}}
 * {{{msttcorefonts}}}
You'll have a really good selection of TrueType fonts at the expense of contaminating your '''Free''' system with non-Free fonts.

All these font packages in Debian should work without any efforts and appear available to all X programs that use the regular "core" font system.  This includes things like Xterm, Emacs, and most other non-KDE and non-GNOME applications.

=== The connection methods to the X server ===

There are several ways of getting the "X server" ('''display''' side) to accept connections from an "X client" ('''application''' side):

|| List of connection methods to the X server. || 2 || 3 || 4 || || ||
|| '''method''' || '''package''' || '''popcon''' || '''size''' || '''user''' ||  '''encryption''' || '''pertinent use''' ||
|| {{{xhost}}} command || {{{xbase-clients}}} || 25829 || - || unchecked || no || deprecated ||
|| {{{xauth}}} command || {{{xbase-clients}}} || 25829 || - || checked || no || for local connection via pipe ||
|| {{{ssh -X}}} command || {{{openssh-client}}} || 29037 || - || checked || yes || for remote network connection ||
|| Gnome display manager || {{{gdm}}} || 17331 || - || checked || no(XDMCP) || for local connection via pipe ||
|| KDE display manager || {{{kdm}}} || 5781 || - || checked || no(XDMCP) || for local connection via pipe ||
|| X display manager || {{{xdm}}} || 645 || - || checked || no(XDMCP) || for local connection via pipe ||
|| WindowMaker display manager || {{{wdm}}} || 253 || - || checked || no(XDMCP) || for local connection via pipe ||
|| Secure display manager || {{{sdm}}} || 25 || - || checked || yes || for remote SSH network connection (thin client) ||
|| Linux Terminal Server Project display manager || {{{ldm}}} || 3 || - || checked || yes || for remote SSH network connection (thin client) ||

/!\  Do not use remote TCP/IP connection over unsecured network unless you have very good reason.  A remote TCP/IP socket connection without encryption is prone to the eavesdropping attack and is disabled by default on the Debian system.  Use {{{ssh -X}}}.

{i} You can dare to enable remote TCP/IP connection by setting {{{DisallowTCP=false}}} in {{{/etc/gdm/gdm.conf}}} and by removing {{{-nolisten}}} from lines found by "{{{find /etc/X11 -type f -print0 | xargs -0 grep nolisten}}}", if you are in the fully secured environment.

/!\  Do not use [http://en.wikipedia.org/wiki/X_display_manager XDMCP connection over unsecured network] either.  It sends data via UDP without encryption and prone to the eavesdropping attack.

== Starting the X window system ==

The X Window system is usually started as an X session which is the combination of an X server and connecting X clients.  For normal desktop system, both of them are executed on the workstation.

To start the X Window system,
 * {{{startx}}} command started from the command line, or 
 * one of the [http://en.wikipedia.org/wiki/X_display_manager X display manager] daemon programs {{{*dm}}} started from the end of the start up script in {{{/etc/rc?.d/}}} directory ({{{?}}} corresponding to the runlevel)
are used to start the [http://en.wikipedia.org/wiki/X_session_manager X session]. (The start up script for the display manager daemons checks the content of the {{{/etc/X11/default-display-manager}}} file before actually executing themselves.)

{i} See @{@specificlocaleonlyunderxwindow@}@ for initial environment variables of the X display manager.

Essentially, all these programs execute the {{{/etc/X11/Xsession}}} script.  Then the {{{/etc/X11/Xsession}}} script performs run-parts like action to execute scripts in the {{{/etc/X11/Xsession.d/}}} directory. This is essentially an execution of a program which was first found in the following order with the {{{exec}}} command:
 1. The script specified as the argument of {{{/etc/X11/Xsession}}} by the X display manager, if it is defined.
 1. The {{{~/.xsession}}} or {{{~/.Xsession}}} script, if it is defined.
 1. The {{{/usr/bin/x-session-manager}}} command, if it is defined.
 1. The {{{/usr/bin/x-window-manager}}} command, if it is defined.
 1. The {{{/usr/bin/x-terminal-emulator}}} command, if it is defined.

This process is affected by the content of the {{{/etc/X11/Xsession.options}}} file.  The exact programs to which these {{{usr/bin/x-*}}} commands point, are determined by the Debian alternative system and changed by {{{update-alternatives --config x-session-manager}}} etc.

=== Starting X session with gdm ===

The {{{gdm}}} program lets you select the session type and language (or locale) of the X session from its menu.  It keeps the selected default value in {{{~/.dmrc}}} as, e.g.:
{{{
[Desktop]
Session=default
Language=ja_JP.UTF-8
}}}

=== Customizing the X session (classic method) ===

On a system where {{{/etc/X11/Xsession.options}}} contains a line {{{allow-user-xsession}}} without preceding {{{#}}} characters, any user who defines {{{~/.xsession}}} or {{{~/.Xsession}}} will be able to customize the action of {{{/etc/X11/Xsession}}} by completely overiding the system code. The last command in the {{{~/.xsession}}} file should use form of {{{exec some-window/session-manager}}} to start your favorite X window/session managers.

=== Customizing the X session (new method) ===

Here are new methods to customize the X session without completely overiding the system code as above.

 * The display manager {{{gdm}}} can select a specific session and set it as the argument of {{{/etc/X11/Xsession}}}.
 * The {{{~/.xsessionrc}}} file is executed as a part of start up process. (Desktop independent)
 * The {{{~/.gnomerc}}} file is executed as a part of start up process. (Gnome Desktop only)
 * The GUI program based session management software can use the {{{~/.gnome2/session}}} file etc..

=== Connecting a remote X client via SSH ===

The use of {{{ssh -X}}} enables a secure connection from a local X server to a remote application server.

 * Set {{{X11Forwarding}}} entries to {{{yes}}} in {{{/etc/ssh/sshd_config}}} of the remote host, if you want to avoid {{{-X}}} command-line option.
 * Start the X server on the local host.
 * Open an {{{xterm}}} in the local host.
 * Run {{{ssh}}} to establish a connection with the remote site.
 {{{
localname @ localhost $ ssh -q -X loginname@remotehost.domain
Password:
.....
}}}
 * Run an X application command, e.g. {{{gimp}}}, on the remote site.
 {{{
loginname @ remotehost $ gimp &
}}}

This method allows the display of the remote X client output as if it were locally connected through a local UNIX domain socket.

=== Secure X terminal via Internet ===

Secure X terminal via Internet, which displays remotely run entire X desktop environment, can easily achieved by using specialized package such as {{{sdm}}} and {{{ldm}}}. Your local machine becomes a secure thin client to the remote application server connected via SSH.

If you want to add similar feature to your normal display manager {{{gdm}}}, create executable shell script at {{{/usr/local/bin/ssh-session}}} as:
{{{
#!/bin/sh -e
# Based on gdm-ssh-session in gdm source (GPL)
ZENITY=$(type -p zenity)
TARGETHOST=$($ZENITY --width=600 \
--title "Host to connect to" --entry \
--text "Enter the name of the host you want to log in to as user@host.dom:")
TARGETSESSION=$($ZENITY --width=600 --height=400 \
--title "Remote session name" --list --radiolist --text "Select one" \
--column " " --column "Session" --column "description" --print-column 2 \
TRUE "/etc/X11/Xsession" "Debian" \
FALSE "/etc/X11/xinit/Xclients" "RH variants" \
FALSE "gnome-session" "Gnome session" \
FALSE "xterm" "Safe choice" \
FALSE "rxvt" "Safe choice" \
FALSE "gnome-terminal" "Safe choice")
echo "Connecting to "$TARGETHOST" with $TARGETSESSION"
/usr/bin/ssh -A -X -T -n "$TARGETHOST" "$TARGETSESSION"
#SSH_ASKPASS=/usr/bin/ssh-askpass /usr/bin/ssh -A -X -T -n "$TARGETHOST" "$TARGETSESSION"
}}}
Then add followings to {{{/etc/dm/Sessions/ssh.desktop}}}:
{{{
[Desktop Entry]
Encoding=UTF-8
Name=SSH
Comment=This session logs you into a remote host using ssh
Exec=/usr/local/bin/ssh-session
Type=Application
}}}

== The X trivia ==

=== Keymaps and pointer button mappings in X ===

The {{{xmodmap}}}(1) program is a utility for modifying keymaps and pointer button mappings in the X window system. 
To get the {{{keycode}}}, run the {{{xev}}} program in the X and press keys.  To get the meaning of {{{keysym}}}, look into the MACRO definition in {{{/usr/include/X11/keysymdef.h}}} file.  All {{{#define}}} statements in this file are named as {{{XK_}}} prepended to {{{keysym}}} names.

=== The classic X clients ===

Most traditional X client programs, such as {{{xterm}}}, can be started with a set of standard command line options to specify geometry, font, and display.  

They also use the X resource database to configure their appearance.  The system-wide defaults of X resources are stored in {{{/etc/X11/Xresources/*}}} and application defaults of them are stored in {{{/etc/X11/app-defaults/*}}}.  Use these settings as the starting points.

The file {{{~/.Xresources}}} is used to store user resource specifications.  This file is automatically merged into the default X resources upon login.  To make changes to these settings and make them effective immediately, merge them into the database using the command:
{{{
$ xrdb -merge ~/.Xresources
}}}

See {{{x}}}(7) and {{{xrdb}}}(1).

=== The X terminal emulator -- xterm ===

Learn everything about {{{xterm}}} at [http://dickey.his.com/xterm/xterm.faq.html].

=== Getting root in X ===

'''Never attempt to start an X server directly from the root account''' in order to avoid possible security risks.

The easiest way to run the X client with the root account is to use {{{sudo}}}, e.g. for {{{xterm}}}:
{{{
$ sudo xterm &
}}}
or
{{{
$ sudo -s
# xterm &
}}}

<!> In order for the X client to connect to the X server, the {{{$HOME/.Xauthority}}} of the old user needs to be readable by the new user.

The {{{gksu}}} package (popcon: @@@pop-gksu@@@) is a specialized GUI package for gaining the root privileges.

=== Web browsers in X ===

There are many [http://en.wikipedia.org/wiki/Web_Browsers web browser] packages with graphical display capabilities:

|| List of web browsers in X. || 1 || 2 || 3 ||
|| '''package''' || '''popcon''' || '''size''' || '''description''' ||
|| {{{iceweasel}}} || 17848 || - || unbranded Firefox, new ||
|| {{{epiphany-browser}}} || 9841 || - || Gnome ||
|| {{{konqueror}}} || 5651 || - || KDE ||
|| {{{iceape-browser}}} || 1804 || - || unbranded Mozilla, old ||

You may use following special URL strings to confirm browser settings.

 * "{{{about:}}}"
 * "{{{about:config}}}"
 * "{{{about:plugins}}}"

Debian offers many free browser plugin packages in the main component which can handle not only [http://en.wikipedia.org/wiki/Java_(software_platform) Java] and [http://en.wikipedia.org/wiki/Adobe_Flash Flash] but also [http://en.wikipedia.org/wiki/MPEG-1 MPEG], [http://en.wikipedia.org/wiki/MPEG-2 MPEG2], [http://en.wikipedia.org/wiki/MPEG-4 MPEG4], [http://en.wikipedia.org/wiki/DivX DivX], [http://en.wikipedia.org/wiki/Windows_Media_Video Windows Media Video (.wmv)], [http://en.wikipedia.org/wiki/QuickTime QuickTime (.mov)], [http://en.wikipedia.org/wiki/MP3 MP3 (.mp3)], [http://en.wikipedia.org/wiki/Vorbis Ogg/Vorbis] files, DVDs, VCDs, etc.  Debian also offers helper programs to install non-free browser plugin packages as contrib or non-free components.

|| List of browser plugin packages. || 1 || 2 || 3 || ||
|| '''package''' || '''popcon''' || '''size''' || '''component''' || '''description''' ||
|| {{{icedtea-gcjwebplugin}}} || - || - || main || Java plugin using Hotspot JIT ||
|| {{{java-gcj-compat-plugin}}} || - || - || main || Java plugin using the gij runtime ||
|| {{{gcjwebplugin}}} || - || - || main || Java plugin using Free Java Virtual Machine ||
|| {{{sun-java5-plugin}}} || - || - || non-free || Java plugin for Sun's Java SE 5.0 (i386 only) ||
|| {{{sun-java6-plugin}}} || - || - || non-free || Java plugin for Sun's Java SE 6 (i386 only) ||
|| {{{swfdec-mozilla}}} || - || - || main || Flash plugin based on libswfdec ||
|| {{{mozilla-plugin-gnash}}} || - || - || main || Flash plugin based on Gnash ||
|| {{{flashplugin-nonfree}}} || - || - || contrib || Flash plugin helper to install Adobe Flash Player (i386, amd64 only) ||
|| {{{mozilla-bonobo}}} || - || - || main || Mozilla plugin support for Gnome Bonobo components ||
|| {{{mozilla-plugin-vlc}}} || - || - || main || Multimedia plugin based on [http://en.wikipedia.org/wiki/VLC_media_player VLC media player] ||
|| {{{totem-mozilla}}} || - || - || main || Multimedia plugin based on [http://en.wikipedia.org/wiki/Totem_(media_player) Gnome's Totem media player] ||
|| {{{gecko-mediaplayer}}} || - || - || main || Multimedia plugin based on (GNOME) [http://en.wikipedia.org/wiki/MPlayer MPlayer] ||

## JAVA: FREE: 1.4 CONTRIB: 1.6 NONFREE >>1.6
## icedtea-gcjwebplugin is really FREE http://bugs.debian.org/492311 thus not controb.
## FLASH: YOUTUBE=YES, GOOGLE STREET VIEW: only NON=FREE
### RC buggy and about to be removed.
### || {{{libflash-mozplugin}}} || - || - || main || Flash plugin based on libflash ||
## GRAPHICS: in order of formats.

{i} Although use of above Debian packages are much easier, browser plugins can be still manually enabled by installing "*.so" into plugin directories (e.g., {{{/usr/lib/iceweasel/plugins/}}}) and restarting browsers.  

Some web sites refuse to be connected based on the user-agent string of your browser.  You can work around this situation by [http://www.mozilla.org/unix/customizing.html#prefs spoofing the user-agent string].  For exaple, you can do this by adding:
{{{
user_pref{"general.useragent.override","Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0)"};
}}}
into user configuration files such as {{{~/.gnome2/epiphany/mozilla/epiphany/user.js}}} or {{{~/.mozilla/firefox/*.default/user.js}}}. Alternatively, you can add and reset this variable by typing "{{{about:config}}}" into URL and right clicking its display contents. 

<!> Spoofed user-agent string may cause [https://bugzilla.mozilla.org/show_bug.cgi?id=83376 bad side effects with Java].

## In order to keep it short and stable, I chose not to include these:
## Other method works varying degree.  
## about:config seems edittable for firefox/iceweasel while ephiphany is just for reset and add.
## * For running X based browsers such as, {{{iceweasel}}}, you can add this variable by typing "{{{about:config}}}" into URL.
## * For running X based mail agents such as {{{icedove}}}, you can add this variable by clicking "Edit" -> "Preferences" -> "Advanced" -> "General" -> "Config Editor".
## * For permanent fix, add "{{{user_pref{"general.useragent.override","Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 4.0)"};}}}" into configuration files such as {{{~/.gnome2/epiphany/mozilla/epiphany/prefs.js}}} or {{{~/.mozilla/firefox/*.default/prefs.js}}}.

## For more information, see http://www.mozilla.org/unix/customizing.html#prefs .
