From 0c7c54145a1e82b88b0d2a5fb311515bb301cf55 Mon Sep 17 00:00:00 2001 From: JMadgwick <32958136+JMadgwick@users.noreply.github.com> Date: Tue, 26 Aug 2025 19:38:52 +0100 Subject: [PATCH 1/3] Add documentation for locale and timezone --- docs/handbook/systems-administration.md | 76 +++++++++++++++++++++---- 1 file changed, 65 insertions(+), 11 deletions(-) diff --git a/docs/handbook/systems-administration.md b/docs/handbook/systems-administration.md index 546f8804..d71e0b45 100644 --- a/docs/handbook/systems-administration.md +++ b/docs/handbook/systems-administration.md @@ -58,7 +58,7 @@ To use the system, a user requires an account, which are known as _user accounts A user account facilitates interactive access to the system and is primarily used for day-to-day tasks. Each user requiring access to the system should have a unique account specifically assigned to that user. -System administrators can thereby monitor user activity and establish system dignostics to optimise system performance. +System administrators can thereby monitor user activity and establish system diagnostics to optimise system performance. Moreover permission to perform various system activities can be separately assigned to each user on an individual basis. When the system is initially installed, usually only one user account is created. @@ -82,7 +82,7 @@ This is often the user's real name. * **home directory** the path to the directory which is _home_ to the user and where the user is placed by default after logging onto the system. * **login shell** user's initial shell program. -* **password last change time** time at which the the user password was last changed. +* **password last change time** time at which the user password was last changed. * password aging information - several [shadow(4)](https://illumos.org/man/4/shadow) fields determining when password should be changed * **min** the minimum number of days required between password changes; * **max** the maximum number of days the password is valid; @@ -148,7 +148,7 @@ To enable some users to carry out a command with root privileges, or to _do_ an Furthermore, in addition to being able to equip users with permission to perform some actions, `sudo` can be applied to a `group`. The group can be assigned to users who are then elevated to the powers available to that group. -One common strategy is to to define a minimum set of commands to perform some task, e.g., manage a mailserver, and then assign these commands to a group. +One common strategy is to define a minimum set of commands to perform some task, e.g., manage a mailserver, and then assign these commands to a group. Thereby, mailserver management can be assigned to a user by adding the group membership to a user. While elevated user privileges for `sudo` are configured in `/etc/sudoers`, user configuration is preferably performed by adding files to the `/etc/sudoers.d/` directory. @@ -178,7 +178,7 @@ It is also dangerous for more than one user to edit this file at the same time. To prevent such mishaps, `visudo` was designed to assist in avoiding such issues. `visudo` works in conjunction with an editor, by default `vi`. -A standard installation of OpenIndian supplies an easy to use editor called `pluma`. +A standard installation of OpenIndiana supplies an easy to use editor called `pluma`. To start `visudo` with it using `pluma`, do the following: ```bash @@ -762,7 +762,7 @@ all packages will be updated to the latest revision: pfexec pkg update ``` -(Note: for `pfexec` to succeed you'll need to have the `Software Installation` profile [enabled for your user account](../getting-started/#quick-start-to-ips).) +(Note: for `pfexec` to succeed you'll need to have the `Software Installation` profile [enabled for your user account](getting-started.md#quick-start-to-ips).) New installation images are beneficial for those @@ -1700,14 +1700,68 @@ Here are just a few of them: ## Localization -
-!!! info "Documentation Team" - ITEMS TO WRITE ABOUT: +### Language + +A *locale* determines the language and encoding use for system and programs' messages, representation of dates and so on. The command `locale` prints the locale currently in use. + +
+!!! note + The output of `locale` can differ depending on how and where the command is run. + For example, ssh sessions from another system usually inherit the client's locale configuration, and different users' desktop environments can use their own locales. +
+ +#### Installing additional locales + +To ensure that a desired locale is present on your system, you can run `locale -a` to list all available locales. +If the desired locale is not already installed, you must install it. Locale package names follow a naming convention `locale\xx`, where **xx** is a 2 letter language code. +For example, to add support for the Macedonian locale, install the package `locale/mk`, or for Simplified Chinese `locale/zh_cn` (`_cn` signifies this is one of multiple variations for this language). + +#### Setting the system default locale + +OpenIndiana stores the default (system) locale in `/etc/default/init`. This is configured during initial installation but can be changed later. + +This is done by editing this file, changing the value of `LANG` to your desired language and rebooting the system. You should use a value from `locale -a` ending with `.UTF-8`. +An invalid value for `LANG` will cause errors and/or American English to be used. + +#### Setting user specific locales (Graphical Desktop) + +By default, when logging into a graphical session the system default locale will be used. However, when there are multiple users on the same system it may be desirable to set locale on a per-user basis. +This can be done by creating a configuration file named `.dmrc` in the user's home directory. +This file is used to specify settings for the display manager (*lightdm*). The example `.dmrc` file below sets the user's locale to German (Germany). + +``` +[Desktop] +Language=de_DE.UTF-8 +``` + +
+!!! note + User specific locale can also be configured in `/var/cache/lightdm/dmrc/user.dmrc` (where *user* is a username). If configured here, all other local configuration (e.g. `.dmrc`) will be **ignored**. +
+ +### Timezone + +The system timezone is configured using the `TZ` key in `/etc/default/init`. As with locale, it should be configured during installation but can be changed later. +The `tzselect` utility can be used to determine the appropriate timezone name to use in `/etc/default/init`. - Possible resources to help write this section: +### Example system localization defaults - * - * +This example of `/etc/default/init` sets the locale to German (Germany) and the timezone to Germany + +``` +TZ=Europe/Berlin +CMASK=022 +LANG=de_DE.UTF-8 +``` + +### Granular localization customization + +It is also possible to configure the system to use certain aspects of one locale in combination with another. Such as using a currency associated with a different language. This is done with `LC_` locale environment variables. +They can be set in `/etc/default/init`. These variables are common to most Unix-like systems and so are not documented here. + +
+!!! note + Avoid setting `LC_ALL` globally, as this will override any local user configuration.
## Dtrace From 9f205ac98dfdfe64c2f66bb0e931605a2d9ccab0 Mon Sep 17 00:00:00 2001 From: JMadgwick <32958136+JMadgwick@users.noreply.github.com> Date: Fri, 29 Aug 2025 21:44:09 +0100 Subject: [PATCH 2/3] Add extra details on environment variables --- docs/handbook/systems-administration.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/handbook/systems-administration.md b/docs/handbook/systems-administration.md index d71e0b45..c42e03ad 100644 --- a/docs/handbook/systems-administration.md +++ b/docs/handbook/systems-administration.md @@ -1720,23 +1720,25 @@ For example, to add support for the Macedonian locale, install the package `loca OpenIndiana stores the default (system) locale in `/etc/default/init`. This is configured during initial installation but can be changed later. -This is done by editing this file, changing the value of `LANG` to your desired language and rebooting the system. You should use a value from `locale -a` ending with `.UTF-8`. +To set default locale, edit this file and change the value of `LANG` to your desired language, then reboot the system. You should use a value from `locale -a` ending with `.UTF-8`. An invalid value for `LANG` will cause errors and/or American English to be used. #### Setting user specific locales (Graphical Desktop) By default, when logging into a graphical session the system default locale will be used. However, when there are multiple users on the same system it may be desirable to set locale on a per-user basis. -This can be done by creating a configuration file named `.dmrc` in the user's home directory. -This file is used to specify settings for the display manager (*lightdm*). The example `.dmrc` file below sets the user's locale to German (Germany). +This can be done by editing (or creating) the `.dmrc` configuration file in the user's home directory. +This file is used to specify settings for the display manager (*lightdm*). The example `.dmrc` file below uses a `Language=` entry to set the user's locale to German (Germany). ``` [Desktop] Language=de_DE.UTF-8 ``` +The locale can also be configured directly in `.profile` or `.xprofile` using the `LANG` environment variable. In OI, [these files are read when *lightdm* starts](https://github.com/OpenIndiana/oi-userland/blob/oi/hipster/components/desktop/lightdm/files/lightdm-session#L31-L36). +
!!! note - User specific locale can also be configured in `/var/cache/lightdm/dmrc/user.dmrc` (where *user* is a username). If configured here, all other local configuration (e.g. `.dmrc`) will be **ignored**. + User specific locale can also be configured in `/var/cache/lightdm/dmrc/user.dmrc` (where *user* is a username). If configured here, all other local configuration (e.g. `.dmrc`, `.xprofile`) will be **ignored**.
### Timezone @@ -1757,7 +1759,7 @@ LANG=de_DE.UTF-8 ### Granular localization customization It is also possible to configure the system to use certain aspects of one locale in combination with another. Such as using a currency associated with a different language. This is done with `LC_` locale environment variables. -They can be set in `/etc/default/init`. These variables are common to most Unix-like systems and so are not documented here. +They can be set globally in `/etc/default/init`, or on a per-user basis in `.profile` or other files read by login shells. These variables are common to most Unix-like systems and so are not documented here.
!!! note From fc36e58a237f3e1cf0813fcfea92c27f8da97be5 Mon Sep 17 00:00:00 2001 From: JMadgwick <32958136+JMadgwick@users.noreply.github.com> Date: Tue, 2 Sep 2025 19:36:34 +0100 Subject: [PATCH 3/3] Fix typos --- docs/handbook/systems-administration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/handbook/systems-administration.md b/docs/handbook/systems-administration.md index c42e03ad..2c7b05ad 100644 --- a/docs/handbook/systems-administration.md +++ b/docs/handbook/systems-administration.md @@ -1702,7 +1702,7 @@ Here are just a few of them: ### Language -A *locale* determines the language and encoding use for system and programs' messages, representation of dates and so on. The command `locale` prints the locale currently in use. +A *locale* determines the language and encoding used for system and programs' messages, representation of dates and so on. The command `locale` prints the locale currently in use.
!!! note @@ -1720,7 +1720,7 @@ For example, to add support for the Macedonian locale, install the package `loca OpenIndiana stores the default (system) locale in `/etc/default/init`. This is configured during initial installation but can be changed later. -To set default locale, edit this file and change the value of `LANG` to your desired language, then reboot the system. You should use a value from `locale -a` ending with `.UTF-8`. +To set the default locale, edit this file and change the value for `LANG` to your desired language, then reboot the system. You should use a value from `locale -a` ending with `.UTF-8`. An invalid value for `LANG` will cause errors and/or American English to be used. #### Setting user specific locales (Graphical Desktop) @@ -1743,7 +1743,7 @@ The locale can also be configured directly in `.profile` or `.xprofile` using th ### Timezone -The system timezone is configured using the `TZ` key in `/etc/default/init`. As with locale, it should be configured during installation but can be changed later. +The system timezone is configured using the `TZ` key in `/etc/default/init`. As with locale, it is usually defined during installation but can be changed later. The `tzselect` utility can be used to determine the appropriate timezone name to use in `/etc/default/init`. ### Example system localization defaults