2,411
edits
Changes
Jump to navigation
Jump to search
mLine 5:
Line 5: − All user-modifiable configuration parameters on the SME Server are stored in the configuration database. These values are used to generate the system configuration files, such as those found in the /etc/ directory.+ − The configuration databases may be modified by various programs on the system, including the SME Server manager, the SME Server console, or scripts run from the command line by a system administrator.+ − Each entry in the database is either a simple key/value pair or a key and a collection of related property/value pairs.+ − Note: The section describes the general structure of the configuration database. The actual entries and properties are subject to change between releases.+ − Simple entries+ − Simple configuration database entries take the form of a key/value pair: − [root@gsxdev1 ~]# config show AccessType+ − AccessType=dedicated − + − ConsoleMode=login+ + − + − TimeZone=Australia/NSW+ − Complex entries+ + − More complex entries consist of a key, a type, and a collection of property/value pairs:+ − + − + + − + − + − In most cases, complex entries are used in preference to simple entries. The complex entries allow additional properties to be stored for an entry, which enhances the system's flexibility. − Access from the command line − You can access configuration database entries from the command line using the config command, as shown above, or the db command. The config command provides a shorthand for accessing the configuration database. The following commands are equivalent:+ − [root@gsxdev1 ~]# config show LocalIP − LocalIP=192.168.1.100 − [root@gsxdev1 ~]# db configuration show LocalIP+ − LocalIP=192.168.1.100 − Note: The term configuration database is used both to refer to the "master" configuration database and to refer collectively to the set of configuration databases, which includes the individual accounts, networks, and configuration databases.+ + + − The db allows you to access all of the databases. For example to show the details of the admin entry from accounts+ + − + − + + + + Line 68:
Line 70: − Documentation for the db command is displayed if you run it without providing any arguments:+ − + − + − Line 87:
Line 88: − Access via the Perl API+ − − You can also access configuration database entries programmatically using the esmith::ConfigDB and related Perl modules, which are abstractions for the esmith::DB module. − For example, we can retrieve and show the admin account details like this:+ − + + + + + − my $db = esmith::AccountsDB->open or die "Couldn't open AccountsDB\n";+ − + − my $admin = $db->get("admin") or die "admin account missing from AccountsDB\n";+ − − print $admin->show(); − − This code fragment would display the same information as running the db accounts show admin command we saw previously. − − Line 115:
Line 112: − The Perl API will be covered in more depth in the exercises later in this manual. For documentation on the API, log into the SME Server and browse the documentation using the perldoc command:+ + + + + + − perldoc esmith::ConfigDB+ − perldoc esmith::AccountsDB − perldoc esmith::HostsDB − perldoc esmith::NetworksDB − perldoc esmith::DB+ + + + − Database initialization+ − The configuration databases are initialized from files in the /etc/e-smith/db/ hierarchy. These files can perform one of three actions:+ − *+ − − Create a database entry and set it to a default value, if the entry does not already exist. − * − − Force a database entry to a specific value, regardless of its current setting. − * − Migrate an entry from a previous value to a new value. + + + + + − This design allows each package to provide part of the system configuration, or migrate the system configuration values as required. Note that a single database property can only be "owned" by one package. Database initialization is run during system install, system upgrade and after new software has been installed.+ + − If you examine the /etc/e-smith/db/configuration/ directory you will see three subdirectories: defaults/, force/ and migrate/ to match the three options above. A similar structure exists for each of the other databases. A new database can be created by populating a new directory tree under the /etc/e-smith/db/ directory.+ − [root@gsxdev1 db]# cd /etc/e-smith/db+ − [root@gsxdev1 db]# ls − accounts domains networks yum_installed − backups hosts spamassassin yum_repositories − configuration mailpatterns yum_available yum_updates − + − defaults force migrate+ − Defaults files+ − Defaults files are simple text files. If the corresponding database key/property already exists, it is skipped. Otherwise, the key/property is created and the value loaded. For example, this file:+ − [root@gsxdev1 db]# cat configuration/defaults/sshd/status+ − disabled − would create the sshd database entry if it doesn't already exist, create the status property for that entry, again if it doesn't already exist, and finally set the status property to disabled.+ − Force files+ − Force files are just like defaults files, except they overwrite the existing value. So, this file:+ − [root@gsxdev1 db]# cat configuration/force/sysconfig/ReleaseVersion+ − 7.0rc2 − would create the ReleaseVersion property of the sysconfig entry and unconditionally set its value to 7.0rc2+ − Migrate fragments − Migrate fragments are small pieces of Perl text which can be used to perform more complex migrations than is possible with defaults and force files. They would normally be used to replace database keys or properties with new names, or to adjust policy settings during an upgrade.+ − Each fragment is passed a reference to the current database in the $DB variable. This variable is an instance of the appropriate esmith::DB subclass, e.g. esmith::AccountsDB when the accounts database migrate fragments are being executed. This means that you can use the methods of that subclass, for example esmith::AccountsDB->users().+ − + − Here is an example of a migrate fragment, which replaces the outdated popd entry with the new name pop3: − − − − − − + − This fragment checks whether the database (the configuration database in this case) has a popd entry. If that entry does not exist, the migrate fragment returns immediately. If the popd entry exists, we need to convert it, so we retrieve the pop3 entry (or create it if it doesn't already exist). We then merge the properties from the popd entry into the pop3 entry and finally delete the popd entry.+ − If this migrate fragment is run again, it will return immediately as the popd entry has already been deleted.+ − Important notes about migrate fragments − *+ − Please be careful with migrate fragments. Although they should only modify entries within the current database, there are no restrictions placed on what they can do. The ability to open and even modify other databases may be required to perform a migration.+ − * − Migrate fragments must be safe to run multiple times. They should migrate the value when required and do nothing in other cases.+ − * − Migrate fragments should never call croak or die. This will cause the database migration to stop. If an error is detected, call carp or warn to note the error in the logs.+ − * − Migrate fragments should be owned by the package requiring the migration so that the migration only occurs when that package is installed.+ − * − Migrate fragments should be self-contained and ideally perform only one migration per fragment.+ − * − It is also possible to initialize and migrate database values in action scripts, but creation of migrate fragments is strongly preferred. Creating defaults is a simple matter of creating text files and migrate fragments require far less code than action scripts.+ − + Line 225:
Line 207: − + + Line 233:
Line 216: − + Line 312:
Line 295: −
SME Server:Documentation:Developers Manual:Chapter2/de (view source)
Revision as of 13:15, 29 September 2007
, 13:15, 29 September 2007Replaced Template:drawBox* (deprecated) with Template:* box and made language independant
==Konfigurations-Datenbank==
==Konfigurations-Datenbank==
===Überblick===
Alle SME Server-Parameter, die durch Benutzer geändert werden können, sind in der Konfigurations-Datenbank gespeichert. Diese Werte werden dann benutzt, um Systemkonfigurationsdateien zu generieren, die im Verzeichnis /etc/ gespeichert werden.
Die Konfigurations-Datenbank kann durch verschiedene Programme geändert werden, über den Server-Manager, die Serverkonsole oder Skripte, die ein Administrator aus der SME Server Shell heraus aufruft.
Jeder Eintrag in der Konfigurationsdatenbank ist entweder ein einfaches Schlüssel/Wert-Paar oder ein Schlüssel und eine Zusammenstellung dazu passender Eigenschaften bzw. Werte-Paare.
{{Note box|type=Anmerkung|Dieser Abschnitt beschreibt die generelle Struktur der Konfigurations-Datenbank. Aktuelle Einträge und Eigenschaften können sich zwischen den Versionen des SME Servers ändern.}}
====Einfache Einträge====
[root@gsxdev1 ~]# config show ConsoleMode
Einfache Einträge in der Konfigurations-Datenbank als Schlüssel/Wert-Paar:
[root@gsxdev1 ~]# config show AccessType
AccessType=dedicated
[root@gsxdev1 ~]# config show TimeZone
[root@gsxdev1 ~]# config show ConsoleMode
ConsoleMode=login
[root@gsxdev1 ~]# config show TimeZone
TimeZone=Australia/NSW
====Komplexe Einträge====
[root@gsxdev1 ~]# config show atalk
Komplexere Einträge bestehen aus einen Schlüssel, einem Typ und einer Zusammenstellung dazu passender Eigenschaften bzw. Werte-Paare:
atalk=service
[root@gsxdev1 ~]# config show atalk
atalk=service
MaxClients=20
MaxClients=20
status=enabled
status=enabled
[root@gsxdev1 ~]# config show dhcpd
[root@gsxdev1 ~]# config show dhcpd
dhcpd=service
dhcpd=service
end=192.168.1.250
end=192.168.1.250
start=192.168.1.65
start=192.168.1.65
status=disabled
status=disabled
In den meisten Fällen werden die komplexeren Einträge gegenüber den einfachen Einträgen bevorzugt, weil damit zusätzliche Eigenschaften gespeichert werden können, um die Flexibilität des Gesamtsystems zu erhöhen.
====Zugriff von der Kommandozeile====
Sie können auf die Konfigurations-Datenbank von der SME Server Shell aus über die Kommandozeile zugreifen, in dem Sie die Befehle ''config'' oder ''db'' verwenden. Dabei ist der ''config''-Befehl die abgekürzte Form. Folgende Befehle sind äquivalent:
[root@gsxdev1 ~]# config show LocalIP
LocalIP=192.168.1.100
[root@gsxdev1 ~]# db configuration show LocalIP
LocalIP=192.168.1.100
[root@gsxdev1 ~]# db accounts show admin
{{Note box|type=Anmerkung|Der Begriff ''Konfigurations-Datenbank'' wird mehrfach benutzt. Er beschreibt sowohl die ''Master''-Konfiguration des Gesamtsystems als auch die Zusammenfassung mehrerer Konfigurations-Datenbanken, in denen die einzelnen Benutzerkonten, Netzwerkeinstellungen usw. enthalten sind.}}
admin=system
Sie können auch mit dem ''db''-Befehl auf die Konfigurations-Datenbanken zugreifen. Um beispielsweise Details für das Benutzerkonto ''admin'' anzeigen zu lassen, geben Sie ein:
[root@gsxdev1 ~]# db accounts show admin
admin=system
EmailForward=local
EmailForward=local
FirstName=Local
FirstName=Local
VPNClientAccess=no
VPNClientAccess=no
Die Dokumentation für den ''db''-Befehl wird Ihnen angezeigt, wenn Sie den ''db''-Befel ohne weitere Argumente benutzen:
[root@gsxdev1 ~]# db
[root@gsxdev1 ~]# db
usage:
usage:
/sbin/e-smith/db dbfile keys
/sbin/e-smith/db dbfile keys
/sbin/e-smith/db dbfile print [key]
/sbin/e-smith/db dbfile print [key]
/sbin/e-smith/db dbfile delprop key prop1 [prop2] [prop3] ...
/sbin/e-smith/db dbfile delprop key prop1 [prop2] [prop3] ...
====Zugriff über die Perl API====
Sie können auch mit Perl-Programmen auf die Konfigurations-Datenbanken zugreifen, wenn Sie ''esmith::ConfigDB'' und zugehörige Perl Module verwenden, die Abstraktionen für die ''esmith::DB module'' sind.
use esmith::AccountsDB;
Zum Beispiel können Sie Details zum Benutzerkonto ''admin'' folgendermaßen anfordern und anzeigen lassen:
use esmith::AccountsDB;
my $db = esmith::AccountsDB->open or die "Couldn't open AccountsDB\n";
my $admin = $db->get("admin") or die "admin account missing from AccountsDB\n";
print $admin->show();
Mit diesem Code-Fragment würden die gleichen Informationen angezeigt wie mit dem Befehl
''db accounts show admin'' aus dem vorigen Abschnitt.
admin
admin
EmailForward = local
EmailForward = local
FirstName = Local
FirstName = Local
type = system
type = system
Die Perl API wird noch deutlich tiefer in den späteren Übungen dieses Handbuchs beschrieben. Die Dokumentation dieser API finden Sie über die SME Server Shell mit dem ''perldoc''-Befehl:
perldoc esmith::ConfigDB
perldoc esmith::AccountsDB
perldoc esmith::HostsDB
perldoc esmith::NetworksDB
perldoc esmith::DB
====Datenbank-Initialisierung====
Die Konfigurations-Datenbanken werden aus dem Dateibaum ''/etc/e-smith/db/'' initialisiert. Darin enthaltene Dateien können jeweils eine von drei verschiedenen Aktionen ausführen:
* Erstellen eines Datenbank-Eintrags mit einem voreingestellten Wert, falls der Eintrag nicht schon existiert
* Erzwingen eines spezifischen Wertes für einen Datenbank-Eintrag unabhängig von der aktuellen Einstellung
* Den Wert eines Datenbank-Eintrags mit einem neuen Wert überschreiben
Dieses Design erlaubt jedem Softwarepaket, Teile des Gesamtsystems zu konfigurieren oder die Konfigurationswerte, auf gewünschte Werte zu ändern.
{{Note box|type=Anmerkung|"Besitzer" einer Datenbank-Eigenschaft ist immer ein einzelnes Softwarepaket.Ein einzelnes(einziges) Datenbankeigentum(-besitz) nur von einem Paket im Besitz sein kann. Die Datenbank-Initialisierung wird während des Systems-Erstinstallation, beim System-Upgrade und nach der Installation neuer Softwarepakete durchgeführt.}}
Das Verzeichnis ''/etc/e-smith/db/configuration/'' besteht aus drei Unterverzeichnissen: defaults/, force/ und migrate/, mit denen die Datenbank-Initialisierung unterstützt wird. Eine ähnliche Struktur finden Sie auch für jede der anderen Datenbanken. Eine neue Datenbank wird über ein neues Verzeichnis im Verzeichnisbaum ''/etc/e-smith/db/'' angelegt.
[root@gsxdev1 db]# cd /etc/e-smith/db
[root@gsxdev1 db]# ls
accounts domains networks yum_installed
backups hosts spamassassin yum_repositories
configuration mailpatterns yum_available yum_updates
[root@gsxdev1 db]# ls configuration/
defaults force migrate
=====Dateien unter ''defaults''=====
Die Dateien unter ''defaults'' sind einfache Textdateien und beihalten die für den Server voreingestellten Werte. Falls das Schlüssel/Werte-Paar in der korrespondierenden Datenbank bereits existiert, wird es bei der Initialisierung üpergangen. Ansonsten wird das Schlüssel/Werte-Paar erzeugt und der ''default''-Wert geladen. Das Beispiel
[root@gsxdev1 db]# ls configuration/
[root@gsxdev1 db]# cat configuration/defaults/sshd/status
disabled
würde einen Eintrag in der ''sshd''-Datenbank, seinen zugehörigen Status erzeugen und diesen auf ''disabled'' setzen, wenn dieser Eintrag noch nicht existiert.
=====Daten unter ''force''=====
Die Dateien unter ''force'' sind ähnlich wie diejenigen unter ''defaults'', sind aber dafür gedacht, existierende Einträge zu überschreiben. So würde die Datei
[root@gsxdev1 db]# cat configuration/force/sysconfig/ReleaseVersion
7.0rc2
die Eigenschaft ''ReleaseVersion'' im Eintrag von ''sysconfig'' ändern und den Wert auf ''7.0rc2'' setzen.
=====Codefragmente=====
Codefragmente sind kleine Stückchen aus Perl-Texten und werden für komplexere Änderungen benutzt, die nicht mit den ''default'' oder ''force''-Dateien durchgeführt werden können. Normalerweise werden Codefragmente benutzt, um Datenbank-Schlüssel oder -Eigenschaften mit neuen Namen zu ersetzen o der um Regeln für die Einstellungen während eines Upgrades zu aktualisieren.
Jedes Fragment enthält einen Verweis auf die passende Konfigurations-Datenbank in der $DB Variable. Diese Variable fungiert als Instanz der passenden ''esmith::DB'' subclass, z.B. ''esmith::AccountsDB'', in der Codefragmente für die Konfigurations-Datenbank der Benutzerkonten ausgeführt werden können. Damit sind die Methode subclass verwendbar. Zum Beispiel für die subclass ''esmith::AccountsDB->users()''.
Hier ist ein Beispiel für Codefragmente, die den veralteten Eintrag für ''popd'' mit dem neuen Namen ''pop3'' ersetzen:
{
{
my $popd = $DB->get("popd") or return;
my $popd = $DB->get("popd") or return;
my $pop3 = $DB->get("pop3") ||
my $pop3 = $DB->get("pop3") ||
$DB->new_record("pop3", { type => "service" });
$DB->new_record("pop3", { type => "service" });
$pop3->merge_props($popd->props);
$pop3->merge_props($popd->props);
$popd->delete;
$popd->delete;
}
}
Mit diesem Fragment wird überprüft, ob die Datenbank (in diesem Fall die Konfigurations-Datenabnk) einen Eintrag für den Dienst ''popd'' enthält. Falls der Eintrag nicht exisiert, wird das Fragment sofort beendet. Ist der Eintrag ''popd'' vorhanden, muss er geändert werden, indem der Eintrag für ''pop3'' abgefragt wird (oder neu erstellt wird, wenn er noch nicht vorhanden ist). Die Eigenschaften der beiden Einträge ''popd'' und ''pop3'' werden anschließend zusammengeführt und schließlich der Eintrag ''popd'' gelöscht.
Bei erneutem Start dieses Migrations-Fragments wird dann festgestellt, dass der ''popd'' Eintrag bereits gelöscht wurde und das Fragment dann sofort beendet.
{{Note box|type=Anmerkung|Wichtige Anmerkungen zu Migrations-Fragmenten
Gehen Sie vorsichtig mit Migrations-Fragmenten um. Auch wenn diese nur die Einträge der aktuellen Datenbank ändern, gibt es keine Beschränkungen darin, was änderbar ist. Um eine Migration durchführen zu können, kann es erforderlich sein, andere Datenbanken öffnen und sogar ändern zu können.
Migrate fragments must be safe to run multiple times. They should migrate the value when required and do nothing in other cases.
Migrate fragments should never call croak or die. This will cause the database migration to stop. If an error is detected, call carp or warn to note the error in the logs.
Migrate fragments should be owned by the package requiring the migration so that the migration only occurs when that package is installed.
Migrate fragments should be self-contained and ideally perform only one migration per fragment.
It is also possible to initialize and migrate database values in action scripts, but creation of migrate fragments is strongly preferred. Creating defaults is a simple matter of creating text files and migrate fragments require far less code than action scripts.}}
Evaluation order: migrate, defaults, force
=====Evaluation order: migrate, defaults, force=====
When a database is loaded:
When a database is loaded:
This order allows migration of old format entries to occur prior to loading of new default values. Remember, defaults will not change an existing database property.
This order allows migration of old format entries to occur prior to loading of new default values. Remember, defaults will not change an existing database property.
Forcing database initialization
=====Forcing database initialization=====
The database is initialized during a number of events, including console-save, so a call to signal-event console-save will evaluate all of the database fragments.
The database is initialized during a number of events, including console-save, so a call to signal-event console-save will evaluate all of the database fragments.
It is an SME Server requirement that all database entries and configuration files must be correctly configured after a "reconfiguration reboot". This is available from the console and server manager and performs the post-upgrade and reboot events. Packages should also provide links in other events (e.g. "email-update" for email related changes) to provide reconfiguration without the reboot.
It is an SME Server requirement that all database entries and configuration files must be correctly configured after a "reconfiguration reboot". This is available from the console and server manager and performs the post-upgrade and reboot events. Packages should also provide links in other events (e.g. "email-update" for email related changes) to provide reconfiguration without the reboot.
Important notes about the configuration databases
=====Important notes about the configuration databases=====
*
*
However, it would be possible to have a host named fredfrog as well as a user named fredfrog as they are stored in separate databases and thus different namespaces.
However, it would be possible to have a host named fredfrog as well as a user named fredfrog as they are stored in separate databases and thus different namespaces.
==Actions und Events==
==Actions und Events==