2,569
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: + + + − + − + Line 11:
Line 14: − + − <div class="NOTE"><blockquote class="NOTE">+ − − '''Note: '''The section describes the general structure of the configuration database. The actual entries and properties are subject to change between releases. − − </blockquote></div><div class="SECT2"> − + Line 35:
Line 34: − + Line 55:
Line 54: − + Line 64:
Line 63: + − <div class="NOTE"><blockquote class="NOTE">+ − − '''Note: '''The term <span class="emphasis">''configuration database''</span> is used both to refer to the "master" <span class="emphasis">''configuration''</span> database and to refer collectively to the set of configuration databases, which includes the individual <span class="emphasis">''accounts''</span>, <span class="emphasis">''networks''</span>, and <span class="emphasis">''configuration''</span> databases. − − </blockquote></div> − − Line 107:
Line 101: − + Line 147:
Line 141: − + Line 171:
Line 165: − + Line 183:
Line 177: − + Line 195:
Line 189: − + Line 221:
Line 215: − + + − + − + Line 246:
Line 241: − + + − <div class="NOTE"><blockquote class="NOTE">+ − + − '''Note: '''The '''console-save''' event is not a "reconfigure everything" event, and only changes items which can be configured from the text-mode console. It is convenient in this case as it performs database initialization and migration. − − − − </blockquote></div></div></div><div class="SECT2"> − + Line 274:
Line 265: − + − + Line 287:
Line 278: − + Line 302:
Line 293: − + Line 309:
Line 300: − + Line 316:
Line 307: − + Line 323:
Line 314: − + Line 330:
Line 321: − +
SME Server:Documentation:Developers Manual:Chapter6 (view source)
Revision as of 23:56, 9 February 2009
, 23:56, 9 February 2009→Important notes about migrate fragments: bug 4997
<div class="PART"><div class="TITLEPAGE">
=II. SME Server internals=
<div class="CHAPTER">
<div class="CHAPTER">
=Configuration database=
==Configuration database==
<div class="SECT1">
<div class="SECT1">
==Overview==
===Overview===
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 <tt class="FILENAME">/etc/</tt> directory.
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 <tt class="FILENAME">/etc/</tt> directory.
Each entry in the database is either a simple key/value pair or a key and a collection of related property/value pairs.
Each entry in the database is either a simple key/value pair or a key and a collection of related property/value pairs.
{{Note box|msg=The section describes the general structure of the configuration database. The actual entries and properties are subject to change between releases.}}
<div class="SECT2">
----
----
===Simple entries===
====Simple entries====
Simple configuration database entries take the form of a key/value pair:
Simple configuration database entries take the form of a key/value pair:
----
----
===Complex entries===
====Complex entries====
More complex entries consist of a key, a type, and a collection of property/value pairs:
More complex entries consist of a key, a type, and a collection of property/value pairs:
----
----
===Access from the command line===
====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 <span class="emphasis">''configuration''</span> database. The following commands are equivalent:
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 <span class="emphasis">''configuration''</span> database. The following commands are equivalent:
[root@gsxdev1 ~]# db configuration show LocalIP
[root@gsxdev1 ~]# db configuration show LocalIP
LocalIP=192.168.1.100
LocalIP=192.168.1.100
{{Note box|msg=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 <var class="LITERAL">admin</var> entry from ''accounts''
The '''db''' allows you to access all of the databases. For example to show the details of the <var class="LITERAL">admin</var> entry from <span class="emphasis">''accounts''</span>
[root@gsxdev1 ~]# db accounts show admin
[root@gsxdev1 ~]# db accounts show admin
----
----
===Access via the Perl API===
====Access via the Perl API====
You can also access configuration database entries programmatically using the <code class="CLASSNAME">esmith::ConfigDB</code> and related Perl modules, which are abstractions for the <code class="CLASSNAME">esmith::DB</code> module.
You can also access configuration database entries programmatically using the <code class="CLASSNAME">esmith::ConfigDB</code> and related Perl modules, which are abstractions for the <code class="CLASSNAME">esmith::DB</code> module.
----
----
===Database initialization===
====Database initialization====
The configuration databases are initialized from files in the <tt class="FILENAME">/etc/e-smith/db/</tt> hierarchy. These files can perform one of three actions:
The configuration databases are initialized from files in the <tt class="FILENAME">/etc/e-smith/db/</tt> hierarchy. These files can perform one of three actions:
----
----
====Defaults files====
=====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:
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:
----
----
====Force files====
=====Force files=====
Force files are just like defaults files, except they <span class="emphasis">''overwrite''</span> the existing value. So, this file:
Force files are just like defaults files, except they <span class="emphasis">''overwrite''</span> the existing value. So, this file:
----
----
====Migrate fragments====
=====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.
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.
----
----
====Important notes about migrate fragments====
=====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.
* 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 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 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 call good termination with return(0) rather than exit(0).
* 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 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.
* 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 <span class="emphasis">''strongly''</span> preferred. Creating defaults is a simple matter of creating text files and migrate fragments require far less code than action scripts.
* 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.
</div><div class="SECT3">
</div><div class="SECT3">
----
----
====Evaluation order: migrate, defaults, force====
=====Evaluation order: migrate, defaults, force=====
When a database is loaded:
When a database is loaded:
----
----
====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.
{{Note box|msg=The '''console-save''' event is not a "reconfigure everything" event, and only changes items which can be configured from the text-mode console. It is convenient in this case as it performs database initialization and migration.
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.}}
</div></div><div class="SECT2">
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====
* The configuration databases should only be modified using the tools and APIs provided.
* The configuration databases should only be modified using the tools and APIs provided.
----
----
==The configuration databases==
===The configuration databases===
<div class="SECT2">
<div class="SECT2">
===Configuration===
====Configuration====
The most important database is the (master) configuration database. This database describes how the system should operate; the type of Internet access to use, how email should be handled, and so on.
The most important database is the (master) configuration database. This database describes how the system should operate; the type of Internet access to use, how email should be handled, and so on.
----
----
===Accounts===
====Accounts====
Account details are stored in the <tt class="FILENAME">accounts</tt> database, as complex entries. We classify accounts into several types, including:
Account details are stored in the <tt class="FILENAME">accounts</tt> database, as complex entries. We classify accounts into several types, including:
----
----
===Domains===
====Domains====
The domains database shows the domains handled by this server, including information about how to handle web requests, and the DNS servers for the domain.
The domains database shows the domains handled by this server, including information about how to handle web requests, and the DNS servers for the domain.
----
----
===Networks===
====Networks====
The networks database details the networks which should be treated as local by this server. Local networks have additional access rights which are denied for other networks.
The networks database details the networks which should be treated as local by this server. Local networks have additional access rights which are denied for other networks.
----
----
===Hosts===
====Hosts====
The hosts database decribes all hosts/machines known to this server and is used to generate DHCP and DNS configuration.
The hosts database decribes all hosts/machines known to this server and is used to generate DHCP and DNS configuration.
----
----
===Other configuration databases===
====Other configuration databases====
There are several other configuration databases stored with the ones listed above, and the system design allows for additional databases to be created as required.
There are several other configuration databases stored with the ones listed above, and the system design allows for additional databases to be created as required.
----
----
==Namespace issues==
===Namespace issues===
All entries in a single database share the same namespace. Users, groups, information bays, printers, and other entries in the accounts database currently all share one namespace. This means that you cannot have a user with the same name as an information bay, group or other entry in the accounts database.
All entries in a single database share the same namespace. Users, groups, information bays, printers, and other entries in the accounts database currently all share one namespace. This means that you cannot have a user with the same name as an information bay, group or other entry in the accounts database.