Changes

82 bytes removed , 12:00, 7 June 2015

→‎Adding new account properties: Add note about emsith perl libs location for SME9.x

Line 7: Line 7:

----

−

=Advanced customization principles=

==Advanced customization principles==

−

==Leveraging the provisioning system for users, groups, and i-bays==

===Leveraging the provisioning system for users, groups, and i-bays===

One of the themes in the SME Server is that concepts such as users, groups, and shared information (information bays) are <span class="emphasis">''simplified''</span> and <span class="emphasis">''reused''</span> in the user interface. SME Server users are email users, filesharing users, web users and users for any other sofware installed on the system.

Line 33: Line 33:

−

~~'''Table 15-1. SME Server software'''~~

{| class="CALSTABLE" border="1"

|+SME Server Account Types

! Account type

! Purpose

| User

| Individual users of the system with local email accounts, home directories, etc.

Line 68: Line 68:

----

−

==Programmatically creating users, groups, and i-bays==

===Programmatically creating users, groups, and i-bays===

You can create users, groups, and i-bays by creating database defaults, or through code. Refer to the useraccounts, groups and ibays panels for examples of how to create these items. You can also create accounts with simple shell scripts.

Line 129: Line 129:

----

−

==Reserving accounts to avoid conflicts with user, group, or i-bay names==

===Reserving accounts to avoid conflicts with user, group, or i-bay names===

If your application creates a new directory within your web site e.g. <tt class="FILENAME">http://www.example.com/magicstuff/</tt>, you should make sure the name isn't <span class="emphasis">''also''</span> used for an information bay, since that would create a conflict. Simply reserve the name by creating a <span class="emphasis">''url''</span>account. This can be done by creating a defaults file:

Line 149: Line 149:

----

−

==Adding new account properties==

===Adding new account properties===

Just as you can spontaneously introduce new configuration settings you can spontaneously introduce new properties as well.

−

{{Note box|msg=You should not create new options for existing properties. For example, if the server-manager can only set three possible values, you should not invent a fourth one. Use another property and raise a bug to suggest the required changes.}}

−

~~<div class~~=~~"NOTE"><blockquote class="NOTE">~~

−

~~'''Note: '''~~ You should not create new options for existing properties. For example, if the server-manager can only set three possible values, you should not invent a fourth one. Use another property and raise a bug to suggest the required changes.

−

~~</blockquote></div>~~

For example, let's say that your application needs a concept of <span class="emphasis">''cell phone number''</span> stored for each user account. This is not a standard property in the SME Server. Your application can simply choose a name for the new property, e.g. <tt class="FILENAME">CellNumber</tt>, and immediately start reading and writing that property for the various users - as though the property had always existed.

Line 214: Line 209:

</form>

</nowiki>

{{Note box|Please note that the path for the esmith perl libraries has changed as of SME Server 9.x to '''/usr/share/perl5/vendor_perl/e-smith'''}}

And the form implementation goes in <tt class="FILENAME">/usr/lib/perl5/site_perl/esmith/FormMagick/Panels/cellnumbers.pm</tt> :

Line 349: Line 346:

----

−

==Using the LDAP server==

===Using the LDAP server===

The SME Server automatically creates and maintains an LDAP <span class="emphasis">''address book''</span>. The LDAP server listens for requests on port 389, which is the standard TCP/IP port for LDAP. At this time, the LDAP server should be considered read-only as it is generated from the system configuration and accounts data. Changes to the LDAP schema will be backed up and restored, but major system reconfiguration may reset the LDAP database to the default schema.

Line 356: Line 353:

----

−

==Data backup==

===Data backup===

The SME Server supports two methods for data backup. For light-usage sites, end users can use their web browser to select a <span class="emphasis">''backup to desktop''</span> option; this creates a compressed file of the configuration databases and all user data on the server, and uploads it to the user's desktop via their web browser.

−

{{Note box|msg=The desktop backup is limited to 2GBytes of data on most operating systems.}}

−

~~<div class~~=~~"NOTE"><blockquote class="NOTE">~~

−

~~'''Note: '''~~ The desktop backup is limited to 2GBytes of data on most operating systems.

−

~~</blockquote></div>~~

For heavier-usage sites, automatic nightly tape backup can be configured.

Line 377: Line 369:

----

−

==Using the MySQL database==

===Using the MySQL database===

The SME Server provides a standard method for performing MySQL database initialization and migration. This is done by creating files in the <tt class="FILENAME">/etc/e-smith/sql/init/</tt> directory. These files are run automatically when MySQL is started, and deleted if they run successfully.

A separate MySQL database and one or more database users should be created for each application. The database password should be stored in the configuration database and either retrieved from the configuration database by the application or passed to the application via an <tt class="FILENAME">httpd.conf</tt> fragment. The password should be automatically generated, unique to this server and this application, and stored as a property in the configuration database for later use in database scripts.

−

{{Note box|msg=Database passwords required for application configuration files should be retrieved from the configuration database.}}

−

~~<div class~~=~~"NOTE"><blockquote class="NOTE">~~

−

~~'''Note: '''~~ Database passwords required for application configuration files should be retrieved from the configuration database.

−

~~</blockquote></div>~~

The MySQL root is automatically generated and configured for command-line MySQL use by the root system user. The MySQL root password should only be used for database maintenance such as creating and deleting databases and performing database backups.

−

{{Warning box|msg=Applications should never use the MySQL root password for access to the database and it should never be entered into application configuration files.}}

−

~~<div class~~=~~"NOTE"><blockquote class="NOTE">~~

−

~~'''Note: ''' <span class="emphasis">''~~ Applications should never use the MySQL root password for access to the database and it should never be entered into application configuration files. ~~''</span>~~

−

~~</blockquote></div>~~

First choose a name for your database, as well as a username to access the data. For example, let's say your database is called '''loggerdemo''', the username is '''loguser''' and the password is '''$loggerdemo{DbPassword}'''. A migrate fragment like this might be used to create the password:

Line 408: Line 390:

use MIME::Base64;

−

my $~~rand =~~ sprintf("%~~08d~~", int(~~1_000_000_000~~ * rand()));

$rec->set_prop('DbPassword', sprintf("%15.0f", int( (1000000000000000) * rand() )));

−

~~my $password = MIME::Base64::encode($rand, "");~~

−

~~$rec->set_prop('DbPassword', $password~~);

}

Line 452: Line 431:

Include the migrate fragment and your template in your RPM. Note that the password generated in this way is unique to this server and this application and automatically stored in the configuration database for later use. This means that it is backed up and restored through the normal server operations.

−

{{Note box|msg=For more documentation on MySQL schema creation commands, see: http://www.mysql.com/documentation/mysql/bychapter/}}

−

~~<div class~~=~~"NOTE"><blockquote class="NOTE">~~

−

~~'''Note: '''~~For more documentation on MySQL schema creation commands, see: http://www.mysql.com/documentation/mysql/bychapter/

−

~~</blockquote></div>~~

In the post-installation section of your RPM, expand the template, and run the <tt class="FILENAME">/etc/rc.d/init.d/mysql.init</tt> script. For example the post-installation section of your RPM SPEC file might look like this:

%post

/etc/e-smith/events/actions/initialize-default-databases (needed if a contrib and it contains DB templates)

expand-template /etc/e-smith/sql/init/loggerdemo-create-schema.sql

−

/etc/rc.d/init.d/mysql.init

/etc/rc.d/init.d/mysql.init start

true

Installing this RPM will create the <tt class="FILENAME">/etc/e-smith/sql/loggerdemo-create-schema.sql</tt> templates (because it is part of the RPM), and the post-installation actions will expand the template and run the <tt class="FILENAME">mysql.init</tt> script, which will execute the schema creation commands and delete the generated file. When the RPM installation is finished, the database schema will have been created, and the MySQL database will be ready to process SQL commands from your application.

Line 486: Line 462:

----

−

==Sending email messages==

===Sending email messages===

If your application needs to send an email message, it should use the SMTP protocol and send the message through the local SMTP server (connect to localhost, port 25).

Line 495: Line 471:

----

−

==Managing the firewall==

===Managing the firewall===

The SME Server approach provides better security than a typical firewall, because the SME Server is managed automatically. Conventional firewalls have complex user interfaces, and require a system administrator to choose policies (e.g. which services should be permitted, which ports should be forwarded, etc.) The SME Server firewall has no user interface. It automatically generates the best ruleset that is consistent with the server settings, and is automatically regenerated whenever the server settings are changed.

Line 502: Line 478:

----

−

===Creating firewall pinholes for your application===

====Creating firewall pinholes for your application====

Let us say that your service needs to provide a public service on TCP/IP port 4321, which is normally blocked by the firewall rules. All that you need to do is define this to the SME Server

Line 510: Line 486:

signal-event remoteaccess-update

−

Note that a firewall hole is only opened if three things are true - the service has a TCPPort (or UDPPort) definition, the service is set to public access, and the service is enabled. Run the commands above, and then these ones:

Note that a firewall hole is only opened if three things are true - the service has a TCPPort (or UDPPort) definition, the service is set to public access, and the service is enabled.

You can open multiple ports.

config set myservice service TCPPort 4321,4322 access public status enabled

Run the commands above, and then these ones:

cp /etc/rc.d/init.d/masq /tmp

Line 541: Line 522:

----

−

===Restricting services to specific external hosts: AllowHosts and DenyHosts===

====Restricting services to specific external hosts: AllowHosts and DenyHosts====

As well as being set to public and private, it is possible to allow or deny remote machines access to a particular service. Let's make the service <var class="LITERAL">public</var> once more, but limit access to one host and one subnet:

Line 573: Line 554:

The firewall rulesets are automatically changed so that instead of allowing access from all hosts <var class="LITERAL">0.0.0.0/0</var>, they now two specific rules to allow the host and network specified, and a new <var class="LITERAL">--jump denylog</var> rule which blocks and logs any others.

−

{{Note box|msg=Hosts which are not listed in <var class="LITERAL">AllowHosts</var> are denied, if this property is configured.}}

−

~~<div class="NOTE"><blockquote class~~=~~"NOTE">~~

−

~~'''Note: '''~~ Hosts which are not listed in <var class="LITERAL">AllowHosts</var> are denied, if this property is configured.

−

~~</blockquote></div>~~

There is also a <var class="LITERAL">DenyHosts</var> property which generates rules to block specific hosts, if this is required. If there is a specific reason to limit access to a service, you should normally use <var class="LITERAL">AllowHosts</var> to list the ones which do require access. The DenyHosts property is provided for completeness and can be useful in specific situations, for example to block mail from a misbehaving mail server while allowing it from all other sites.

Line 585: Line 561:

----

−

==Starting up programs automatically upon system boot==

===Starting up programs automatically upon system boot===

If your package implements a server or daemon, you will probably want it to be started automatically when the system boots.

−

The SME Server boots in runlevel 7, so you can get an idea of the startup processes by listing the contents of <tt class="FILENAME">/etc/rc.d/rc7.d</tt>.

The SME Server 8.1 boots in runlevel 7, SME Server 9.0 boots in runlevel 4, so you can get an idea of the startup processes by listing the contents of <tt class="FILENAME">/etc/rc.d/rc7.d</tt>. (or rc4.d for SME Server 9.0)

These are similar to the init scripts you may be familiar with from other Linux systems, with one important differnce. Instead of pointing to scripts within <tt class="FILENAME">/etc/rc.d/init.d</tt>, all of those init entries are links to <tt class="FILENAME">/etc/rc.d/init.d/e-smith-service</tt>. This is a wrapper which checks the configuration database to see if the service is supposed to be running and if so, starts the service from <tt class="FILENAME">/etc/rc.d/init.d/whatever</tt>.

Line 603: Line 579:

Here is the step-by-step procedure for making your package start up a program called <tt class="FILENAME">myserver</tt> at boot time.

−

# First, create the traditional init script <tt class="FILENAME">/etc/rc.d/init.d/myserver</tt> which can be run with the command-line arguments "start" or "stop" to perform the appropriate action on the server. Look at other init scripts in the same directory for examples. This script should be included in your RPM.~~<div class~~=~~"NOTE"><blockquote class="NOTE">'''Note: '''~~ If your service is managed by runit, all you need is a link to the '''daemontools''' script.~~</blockquote></div>~~

{{Note box|msg=If your service is managed by runit, all you need is a link to the '''daemontools''' script.}}

# Second, create a symbolic link as shown below, choosing the two-digit number after the letter S to control the startup order of the server programs. Include this symbolic link in your RPM. /etc/rc.d/rc7.d/S55myserver -> /etc/rc.d/init.d/e-smith-serviceThese two steps are typical for any Linux/Unix server application, except that the symbolic link traditionally points directly to the init script, rather than to <tt class="FILENAME">e-smith-service</tt>. Remember, we want to link to <tt class="FILENAME">e-smith-service</tt> to ensure that a <var class="LITERAL">disabled</var> service does <span class="emphasis">''not''</span> start at boot time.

−

# Third, let's assume for now that <var class="LITERAL">myserver</var> should be enabled by default, and so start at boot time. You just need to create some properties in the configuration database to make that happen: cd /etc/e-smith/db/configuration/defaults

cd /etc/e-smith/db/configuration/defaults

mkdir myserver

cd myserver

echo service >type

−

echo enabled >~~statusFor~~ testing, you will also need to run '''initialize-default-databases''' to load these new defaults.

echo enabled >status

−

# Your RPM can also start the service in the <var class="LITERAL">%post</var> section, but you need to be very careful to only do this in run-level 7. The same <var class="LITERAL">%post</var> section is run during installation from CDROM, and we do not want services started during that installation. They will most likely fail and may cause the CD install to fail.

For testing, you will also need to run '''initialize-default-databases''' to load these new defaults.

Your RPM can also start the service in the <var class="LITERAL">%post</var> section, but you need to be very careful to only do this in run-level 7. The same <var class="LITERAL">%post</var> section is run during installation from CDROM, and we do not want services started during that installation. They will most likely fail and may cause the CD install to fail.

All of these steps result in the server starting automatically upon installation of the RPM, and whenever the server is rebooted.

RequestedDeletion

3,704

edits

Retrieved from "https://wiki.koozali.org/Special:MobileDiff/9411...27822"

Changes

SME Server:Documentation:Developers Manual:Chapter15 (view source)

Revision as of 12:00, 7 June 2015

Navigation menu

Search