Kiosk framework

The KIOSK framework provides an easy way to disable certain features within TDE to create a more controlled environment.

TDE's KIOSK framework builds on TDE's configuration framework and adds a simple application API that applications can query to get authorisation for certain operations.

One of the driving forces behind TDE is to put the user in control and give them a large amount of possibilities to adjust TDE to their liking. However, in some situations it is required to reduce the possibilities of TDE, e.g. because the system is to be used for one or more specific dedicated tasks only.

Warning!

The TDE kiosk-framework should be used in addition to the standard UNIX security measures.

A short history of the KDE configuration framework

Since the very beginning TDE makes use of file-hierarchy to store resources for its applications. Resources range from icons, wallpapers, fonts to sounds, menu-descriptions and configuration files.

KDE1 & KDE2

In KDE1 there were two locations were resources could be located: The resources provided by the system were located under $TDEDIR and user- specific resources were located under $HOME/.kde.

In KDE2 resource management has been largely abstracted by the introduction of the TDEStandardDirs class and has become much more flexible. The user / administrator can now specify a variable number of locations where resources can be found. A list of locations can either be specified via $TDEDIRS (notice the extra 'S'), via /etc/tderc and even via the kdeglobals config file. The location where user-specific resources can be found can be set with $TDEHOME (The default in KDE was $HOME/.kde, in Trinity it's usually $HOME/.trinity). Changes made by the user are always written back to $TDEHOME.

Both KDE1 and KDE2 feature so called "cascading configuration files": There can be multiple configuration files with the same name in the various locations for (config) resources, when that is the case, the information of all these configuration files is combined on a key by key basis. If the same key (within a certain group) is defined in more than one place, the value of the key for the config file that was read last will override any previously read values. Configuration files under $TDEHOME are always read last. This ensures that after a configuration entry is written, the same value wil be read back.

KDE3 & TDE

In KDE3 two important changes have been made:

• Default values are no longer written.

When a configuration file in a location other than $TDEHOME defines a value for a key and the application subsequently writes out a new configuration file to $TDEHOME, that configuration file will only contain an entry for the key if its value differs from the value read from the other file.

This counters the problem that changing default configuration files under $TDEDIR would not take effect for users, since these users would most likely have their own copy of these settings under $TDEHOME. TDE will make sure not to copy these settings so changes made under $TDEDIR will affect all users that haven't explicitly changed the affected settings to something else.

• Configuration entries can be marked "immutable".

Starting with KDE3, configuration entries can be marked "immutable". When a configuration entry is immutable it means that configuration files that are read later will not be able to override its value. Immutable entries cannot be changed via TDEConfig and if the entry is present under $TDEHOME it will be ignored.

Immutable settings

When configuration files are marked immutable in whole or in part the user will no longer be able to make permanent changes to the settings that have been marked immutable. Ideally the application will recognize this and will no longer offer the user the possibility to change these settings. Unfortunately not all applications support this at the moment. It's therefor possible that the user will still be presented with an option in the user interface to change a setting that is immutable, changes made this way will not be saved though. In some cases the user may be able to use the changed setting till the application terminates, in other cases the changed setting will simply be ignored and the application will continue to work with the immutable setting.

Entries can be marked immutable on 4 different levels:

1) On an entry by entry basis by appending [$i] after the key.

Example:

[MyGroup]
someKey[$i]=42

2) On a group by group basis by appending [$i] after the group. All entries specified in the group will be marked immutable and no new entries can be added to the group.

Example:

[MyGroup][$i]
someKey=42

3) On a file by file basis by starting the file with [$i].

Example:

[$i]
[MyGroup]
someKey=42
[MyOtherGroup]
someOtherKey=11

4) On a directory basis. [Not yet implemented]

The filesystem can also be used to mark files immutable. If TDE does not have write-access to the user's version of a configuration file, the file will be automatically considered immutable.

To make the configration file of kicker (the panel) immutable one could for example use the commands below.

Example:

$ chown root.root /home/user/.trinity/share/config/kickerrc
$ chmod 644 /home/user/.trinity/share/config/kickerrc

If you do this, the user will be warned that the configuration file is not writable. Since you will normally not want that, you can add the following two lines to the application's configuration file (or to kdeglobals to disable the warning for all applications):

[KDE Action Restrictions]
warn_unwritable_config=false

Note that the above example is not fool-proof, the user can potentially still rename either the root-owned kickerrc file or any of the directories in the path to another name and create a new kickerrc with write-access.

The following applications currently detect when their configuration files have been marked immutable and adjust their user interface accordingly:

• kicker - By marking the kickerrc config file as immutable, the panel will be

"locked down" and it will not be possible to make any changes to it.

• kdesktop - By marking the kdesktoprc config file as immutable, the desktop

will be "locked down" and it will no longer be possible to select "Configure Desktop" from its menus.

• kcalc - By marking the kcalcrc config file as immutable, the "Configure" button

will not be shown

TDE Action Restrictions

Most functionality within TDE is coupled to so called actions. For example when a user selects the File->Open option in the menubar of a TDE application, the file_open action is activated. Likewise, toolbar icons are usually also coupled to actions. TDE makes it possible to disable functionality by restricting specific actions. By restricting the file_open action for example, the corresponding entry in the menubar and the corresponding icon on the toolbar, if any, will disappear.

To restrict access to function the kdeglobals file should contain the group [KDE Action Restrictions], each action can then be restricted by adding <action>=false. E.g. to disable the action shell_access one would add:

[KDE Action Restrictions][$i]
shell_access=false

Actions

Actions that refer to menu and toolbar actions are prefixed with action/.

For actions marked with (*) see notes below.

Standard actions
action/file_new	action/file_open	action/file_open_recent	action/file_save
action/file_save_as	action/file_revert	action/file_close	action/file_print
action/file_print_preview	action/file_mail	action/file_quit	action/edit_undo
action/edit_redo	action/edit_cut	action/edit_copy	action/edit_paste
action/edit_select_all	action/edit_deselect	action/edit_find	action/edit_find_next
action/edit_find_last	action/edit_replace	action/view_actual_size	action/view_fit_to_page
action/view_fit_to_width	action/view_fit_to_height	action/view_zoom_in	action/view_zoom_out
action/view_zoom	action/view_redisplay	action/go_up	action/go_back
action/go_forward	action/go_home	action/go_previous	action/go_next
action/go_goto	action/go_goto_page	action/go_goto_line	action/go_first
action/go_last	action/bookmarks (*)	action/bookmark_add	action/bookmark_edit
action/tools_spelling	action/options_show_menubar	action/options_show_toolbar (*)	action/options_show_statusbar
action/options_save_options	action/options_configure	action/options_configure_keybinding	action/options_configure_toolbars
action/options_configure_notifications	action/help (*)	action/help_contents	action/help_whats_this
action/help_report_bug	action/help_about_app	action/help_about_kde	action/fullscreen

TDE File Dialog
Action	Description		Action	Description
action/home	Go to home directory		action/up	Go to parent directory
action/back	Go to previous directory		action/forward	Go to next directory
action/reload	Reload directory		action/mkdir	Create new directory
action/toggleSpeedbar	Show/hide sidebar		action/sorting menu	Sorting options
action/short view	Select short view		action/detailed view	Select detailed view
action/show hidden	Show/hide hidden files		action/preview	Show/hide preview
action/separate dirs	Show/hide separate directories

Konqueror & KDesktop related
Action	Description		Action	Description
action/editfiletype			action/properties
action/openwith			action/openintab
action/kdesktop_rmb	RMB menu (*)		action/iconview_preview
action/sharefile	File sharing (*)		action/sendURL	Send Link Address
action/sendPage	Send File		action/devnew	Create New -> Device
action/incIconSize	Increase icon size		action/decIconSize	Decrease icon size
action/go	Entire go menu		action/configdesktop	Configure desktop in RMB menu, see also Control Module Restrictions
action/executeshellcommand	In Konqueror Tools menu, see also shell_access		action/show_dot	Show Hidden Files (*)

Kicker related
Action	Description
action/kicker_rmb	RMB menu
action/menuedit

TWin related
Action	Description
action/twin_rmb	RMB window context menu

Screensaver related
Action	Description
opengl_screensavers	Defines whether OpenGL screensavers are allowed to be used.
manipulatescreen_screensavers	Defines whether screensavers that manipulate an image of the screen (e.g. moving chunks of the screen around) are allowed to be used.

Printing related
Action	Description
print/system	Disables the option to select the printing system (backend). It is recommended to disable this option once the correct printing system has been configured.
print/properties	Disables the button to change printer properties or to add a new printer.'
print/options	Disables the button to select additional print options.
print/copies	Disables the panel that allows users to make more than one copy.
print/selection	Disables the options that allows selecting a (pseudo) printer or change any of the printer properties. Make sure that a proper default printer has been selected before disabling this option. Disabling this option also disables print/system, print/options and print/properties.
print/dialog	Disables the complete print dialog. Selecting the print option will immediately print the selected document using default settings. Make sure that a system wide default printer has been selected. No application specific settings are honored.

Konsole related
action/konsole_rmb	action/settings	action/show_menubar	action/show_toolbar
action/scrollbar	action/fullscreen	action/bell	action/font
action/keyboard	action/schema	action/size	action/history
action/save_default	action/save_sessions_profile	action/options_configure_notifications	action/options_configure_keybinding
action/options_configure	action/send_signal	action/bookmarks	action/add_bookmark
action/edit_bookmarks	action/clear_terminal	action/reset_clear_terminal	action/find_history
action/find_next	action/find_previous	action/save_history	action/clear_history
action/clear_all_histories	action/detach_session	action/rename_session	action/zmodem_upload
action/monitor_activity	action/monitor_silence	action/send_input_to_all_sessions	action/close_session
action/new_session	action/activate_menu	action/list_sessions	action/move_session_left
action/move_session_right	action/previous_session	action/next_session	action/switch_to_session_1
action/switch_to_session_2	action/switch_to_session_3	action/switch_to_session_4	action/switch_to_session_5
action/switch_to_session_6	action/switch_to_session_7	action/switch_to_session_8	action/switch_to_session_9
action/switch_to_session_10	action/switch_to_session_11	action/switch_to_session_12	action/bigger_font
action/smaller_font	action/toggle_bidi

Other defined actions
Action	Description
shell_access	Defines whether a shell suitable for entering random commands may be started. This also determines whether the "Run Command" option (Alt-F2) can be used to run shell-commands and arbitrary executables. Likewise, executables placed in the user's Autostart folder will no longer be executed. Applications can still be autostarted by placing .desktop files in the $TDEHOME/Autostart or $TDEDIR/share/autostart directory. See also run_desktop_files.
custom_config	Defines whether the --config command line option should be honored. The --config command line option can be used to circumvent locked-down configuration files.
logout	Defines whether the user will be able to logout from TDE.
lock_screen	Defines whether the user will be able to lock the screen.
run_command	Defines whether the "Run Command" (Alt-F2) option is available.
movable_toolbars	Defines whether toolbars may be moved around by the user. See also action/options_show_toolbar.
editable_desktop_icons	Defines whether icons on the desktop can be moved, renamed, deleted or added. You might want to set the path for the Desktop to some read-only directory as well. (Instead of $HOME/Desktop)
run_desktop_files	Defines whether users may execute desktop files that are not part of the default desktop, TDE menu, registered services and autostarting services. The default desktop includes the files under $TDEDIR/share/kdesktop/Desktop but NOT the files under $HOME/Desktop. The TDE menu includes all files under $TDEDIR/share/applnk and $XDGDIR/applications Registered services includes all files under $TDEDIR/share/services. Autostarting services include all files under $TDEDIR/share/autostart but NOT the files under $TDEHOME/Autostart You probably also want to activate the following resource restictions: appdata_kdesktop To restrict the default desktop. apps To restrict the TDE menu. xdgdata-apps To restrict the TDE menu. services To restrict registered services. autostart To restrict autostarting services. Otherwise users can still execute .desktop files by placing them in e.g. $TDEHOME/share/kdesktop/Desktop.
lineedit_text_completion	Defines whether input lines should have the potential to remember any previously entered data and make suggestions based on this when typing. When a single account is shared by multiple people you may wish to disable this out of privacy concerns.
start_new_session	Defines whether the user may start a second X session. See also the tdm configuration.
switch_user	Defines whether user switching via tdm is allowed
skip_drm	Defines if the user may omit DRM checking. Currently only used by kpdf

Notes

• action/options_show_toolbar will also disable the "Toolbars" submenu if present.

• action/bookmarks also disables action/bookmark_add and action/bookmark_edit

• action/help is not yet fully implemented

• action/kdesktop_rmb disables the RMB menu but some actions may still be accessible via keyboard shortcuts: cut/copy/rename/trash/delete

• action/iconview_preview disables the option to toggle previews on or off in icon mode but the actual preview settings remains unaffected. To disable previews you also need to add the following lines to konqiconviewrc:

[Settings]
PreviewsEnabled[$i]=false

• action/show_dot disables the option to toggle showing hidden files, the actual setting remains unaffected. To disable showing hidden files, add the following lines to konqiconviewrc:

[Settings]
ShowDotFiles[$i]=false

• action/sharefile disables file sharing from the UI, but you may also want to disable file sharing altogether.

Applications may use additional actions that they defined themselves. You can get a list of the actions used by a certain applications by using the following dcop command:

$ dcop <dcopid> qt objects | grep TDEActionCollection/ | cut -d '/' -f 3

or with

$ dcop <dcopid> <maindwindowid> actions

Actions that refer to applications that need to be run as a different user are prefixed by user/ and identified by the username. For example, this will disable all application entries that require root access:

user/root=false

Application .desktop files can have an additional field "X-TDE-AuthorizeAction". If this field is present the .desktop file is only considered if the action(s) mentioned in this field has been authorized. If multiple actions are listed they should be separated by commas (','). So if the .desktop file of an application lists one or more actions this way and the user has no authorization for one of these actions then the application will not appear in the TDE menu and will not be used by KDE for opening files.

Important note

Changing restrictions may influence the data that is cached in the tdesycoca

database. Since changes to .../share/config/kdeglobals do not trigger an automatic tdesycoca update you need to force an update manually. To force an update of the tdesycoca database touch the file .../share/services/update_tdesycoca. This will force a user's sycoca database

to be rebuild the next time the user logs in.

TDE URL Restrictions

It is also possible to restrict URL related actions. The restriction framework can disable URL actions based on the action, the URL in question and in some cases the referring URL. URLs can be matched based on protocol, host and path.

The syntax for adding URL action restrictions to kdeglobals is as follows:

[KDE URL Restrictions]
rule_count=<N>
rule_1=<action>,<referingURL_protocol>,<referingURL_host>,<referingURL_path>,<URL_protocol>,<URL_host>,<URL_path>,<enabled>
...
rule_N=<action>,<referingURL_protocol>,<referingURL_host>,<referingURL_path>,<URL_protocol>,<URL_host>,<URL_path>,<enabled>

The following actions are supported:

Action	Description
redirect	e.g. a html-page obtained via HTTP could redirect itself to file:/path/some-file. This is disabled by default but could be explicitly enabled for a specific HTTP host. This also applies to links contained in html documents. Example: rule_1=redirect,http,myhost.acme.com,,file,,,true
list	This controls which directories can be browsed with KDE's file-dialogs. If a user should only be able to browse files under home directory one could use: rule_1=list,,,,file,,,false rule_2=list,,,,file,,$HOME,true The first rule disables browing any directories on the local filesystem. The second rule then enables browsing the users home directory.
open	This controls which files can be opened by the user in applications. It also affects where users can save files. To only allow a user to open the files in his own home directory one could use: rule_1=open,,,,file,,,false rule_2=open,,,,file,,$HOME,true rule_3=open,,,,file,,$TMP,true Note that with the above, users would still be able to open files from the Internet and that the user is also given access to $TMP in order to ensure correct operation of TDE applications. $TMP is replaced with the temporary directory that TDE uses for this user.

Some remarks:

• empty entries match everything
• host names may start with a wildcard, e.g. *.acme.com
• a protocol also matches similar protocols that start with the same name, e.g. http matches both http and https. You can use "http!" if you only want to match http (and not https)
• specifying a path matches all URLs that start with the same path. For better results you should not include a trailing slash. If you want to specify one specific path, you can add an exclamation mark. E.g. /srv matches both /srv and /srv/www but "/srv!" only matches /srv and not /srv/www.

TDE Resource Restrictions

Most TDE applications make use of additional resource files that are typically located in directories under $TDEDIR/share. By default TDE allows users to override any of these resources by placing files in the same location under $TDEHOME/share. For example, Konsole stores profiles under $TDEDIR/share/apps/konsole and users can add additional profiles by installing files in $TDEHOME/share/apps/konsole.

TDE Resource Restrictions make it possible to restrict the lookup of files to directories outside of $TDEHOME only.

The following resources are defined:

autostart	share/autostart
data	share/apps
html	share/doc/tde/HTML
icon	share/icon
config	share/config
pixmap	share/pixmaps
apps	share/applnk
xdgdata-apps	share/applications
sound	share/sounds
locale	share/locale
services	share/services
servicetypes	share/servicetypes
mime	share/mimelnk
wallpaper	share/wallpapers
templates	share/templates
exe	bin
lib	lib

For the purpose of resource restrictions there are two special resources:

all	covers all resources
data_<appname>	covers the sub section for <appname> in the data resource.

To restrict resources the kdeglobals file should contain the group [KDE Resource Restrictions], each resource can then be restricted by adding <resource>=false. E.g. to restrict the "wallpaper" resource to $TDEDIR/share/wallpapers one would add:

[KDE Resource Restrictions][$i]
wallpaper=false

And to prevent a user from adding additional konsole profiles, one would add:

[KDE Resource Restrictions][$i]
data_konsole=false

Control Module Restrictions

It is possible to restrict access to particular control modules. Although it is possible to remove control modules from the Control Center by editing the menu structure, such modules will then still be available to applications. A better way is to use the control module restrictions offered by KIOSK:

[TDE Control Module Restrictions][$i]
<menu-id>=false

Some example menu-ids are:

tde-display.desktop
tde-proxy.desktop
tde-screensaver.desktop

See also $ tdecmshell --list for a list of all the base names.

Expansion of environment variables in TDE config files

In TDE arbitrary entries in configuration files can contain environment variables. In order to use this the entry must be marked with [$e].

Example:

Name[$e]=$USER

When the Name entry is read $USER will be replaced with the value of the $USER environment variable. Note that the application will replace $USER with the value of the environment variable after saving. To prevent this combine the $e option with $i (immmutable) option.

Example:

Name[$ei]=$USER

The above will make that the "Name" entry will always return the value of the $USER environment variable. The user will not be able to change this entry.

The following syntax is also supported:

Name[$ei]=${USER}

TDE Kiosk Application API

Three new methods have been added to TDEApplication:

Method	Description
bool authorize(TQString action);	Generic actions
bool authorizeTDEAction(TQString action);	For TDEActions exclusively
bool authorizeURLAction(TQString, referringURL, destinationURL);	URL Handling

Automatic Logout

Since KDE 3.4 it is possible to automatically logout users that have been idle for a certain period of time.

Warning!

Be careful with this option, logging out a user may result in data loss!

In kdesktoprc you can use the following entry to enable automatic logout:

[ScreenSaver]
AutoLogout=true
AutoLogoutTimeout=600

The AutoLogoutTimeout is the time in seconds that the user has to be idle before their session is logged out.