2,411
edits
Changes
Jump to navigation
Jump to search
mLine 13:
Line 13: − + Line 55:
Line 55: − + − + Line 90:
Line 90: − + − For example, we can retrieve and show the admin account details like this:+ + + + + − 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(); − − This code fragment would display the same information as running the db accounts show admin command we saw previously. − − Line 116:
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]# ls+ − accounts domains networks yum_installed − backups hosts spamassassin yum_repositories − configuration mailpatterns yum_available yum_updates − [root@gsxdev1 db]# ls configuration/+ − − 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+ − − 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:+ − + − + − 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 226:
Line 207: − + + Line 234:
Line 216: − +
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
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.
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.
{{DrawBoxNote/de|Inhalt=Dieser Abschnitt beschreibt die generelle Struktur der Konfigurations-Datenbank. Aktuelle Einträge und Eigenschaften können sich zwischen den Versionen des SME Servers ändern.}}
{{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.}}
LocalIP=192.168.1.100
LocalIP=192.168.1.100
{{DrawBoxNote/de|Inhalt=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.}}
{{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.}}
Sie können auch mit dem ''db''-Befel auf die Konfigurations-Datenbanken zugreifen. Um beispielsweise Details für das Benutzerkonto ''admin'' anzeigen zu lassen, geben Sie ein:
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
[root@gsxdev1 ~]# db accounts show admin
admin=system
admin=system
====Zugriff über die Perl API====
====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, which are abstractions for the esmith::DB module.
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.
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]# cd /etc/e-smith/db
[root@gsxdev1 db]# ls configuration/
defaults force migrate
=====Dateien unter ''defaults''=====
defaults force migrate
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]# 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.
disabled
=====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
[root@gsxdev1 db]# cat configuration/force/sysconfig/ReleaseVersion
7.0rc2
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=====
*
*