Changes

From SME Server
Jump to navigationJump to search
14,808 bytes added ,  07:19, 11 November 2015
m
pico -> nano
Line 1: Line 1:  +
{{Languages|Template Tutorial}}
 
===Overview and Description===
 
===Overview and Description===
   Line 49: Line 50:     
Please review the many Howtos and Contrib wiki articles that have these types of configuration changes described, as it will provide step by step examples which can be applied to a particular need (changing the service and fragment names & the expansion config names of course). Also search the Forums on expand-template for numerous examples.
 
Please review the many Howtos and Contrib wiki articles that have these types of configuration changes described, as it will provide step by step examples which can be applied to a particular need (changing the service and fragment names & the expansion config names of course). Also search the Forums on expand-template for numerous examples.
 +
 +
===Template fragment code - perl vs text===
 +
 +
Some templates are inserted as literal text into the output files, and some templates are actually running perl code to generate the output text.
 +
 +
The template fragments using perl code, include braces ("{" and "}") and will likely contain lines beginning with
 +
 +
$OUT .= "blah, blah, blah";
 +
 +
If the template you have copied includes perl code, you will need to write the appropriate perl code to create your new output, or place your text changes after the final closing brace ("}") of the perl commands.
 +
 +
===templates.metadata===
 +
Template output file location, ownership, and other metadata can also be controlled by configuration settings stored under /etc/e-smith/templates.metadata.
 +
 +
While the default output location for most templated config files matches the path to the collection of template fragements, it is also possible to specify a different output filename using an entry within the /etc/e-smith/templates.metadata folder.
 +
 +
====/var/service/qpsmtpd/config/peers/0====
 +
The qpsmtpd 'plugins' directives in /etc/e-smith/templates/var/service/qpsmtpd/config/plugins do NOT affect the content of /var/service/qpsmtpd/plugins as expected.
 +
 +
Instead, due to this line in /etc/e-smith/'''templates.metadata'''/var/service/qpsmtpd/config/plugins:
 +
OUTPUT_FILENAME="/var/service/qpsmtpd/config/peers/0"
 +
 +
This command:
 +
expand-template /var/service/qpsmtpd/config/plugins
 +
 +
Will actually update the contents of /var/service/qpsmtpd/config/peers/0.
 +
 +
Note: /var/service/qpsmtpd/config/plugins is not templated at this time.
 +
 +
====/etc/samba/smb.cnf====
 +
/etc/samba/smb.cnf is updated based on the template fragments in /etc/e-smith/templates/etc/smb.cnf
    
===Specific practical examples===
 
===Specific practical examples===
 +
 +
These are examples only, please ensure you determine and use the correct settings and template fragments.
 +
 +
====dhcpd.conf====
 +
 +
Examine the template fragments in /etc/e-smith/templates/etc/dhcpd.conf and determine which fragment you wish to change.
 +
Let's say you want to modify a value that is in 25DomainNameServers fragment (for the DNS server setting), and in the 25Routers fragment (for the gateway/router setting).
 +
 +
Copy the fragments to the custom template tree
 +
mkdir -p /etc/e-smith/templates-custom/etc/dhcpd.conf
 +
echo "option domain-name-servers 4.2.2.1;" > /etc/e-smith/templates-custom/etc/dhcpd.conf/25DomainNameServers
 +
echo "option routers 192.168.1.4;" > /etc/e-smith/templates-custom/etc/dhcpd.conf/25Routers
 +
Expand template and restart dhcpd
 +
expand-template /etc/dhcpd.conf
 +
sv t /service/dhcpd
 +
 +
Examine /etc/dhcpd.conf to see that your changes have been created.
 +
 +
====masq====
 +
 +
Examine the template fragments in /etc/e-smith/templates/etc/rc.d/init.d/masq
 +
 +
Let's say you wish to block access to your server from an external IP, and there is no fragment that is suitable. Refer http://forums.contribs.org/index.php/topic,45495.0.html In this case create a new fragment.
 +
 +
Create a new template fragment
 +
nano -w /etc/e-smith/templates-custom/etc/rc.d/init.d/masq/40DenyZombies
 +
Add the following to the fragment
 +
/sbin/iptables -A INPUT -s 24.71.223.10/32 -j DROP # waste of space IP
 +
/sbin/iptables -A INPUT -s 24.64.0.0/13 -j DROP # supporting telco
 +
Then save and exit
 +
Ctrl x
 +
yes
 +
Expand template and restart masq (masquerading)
 +
expand-template /etc/rc.d/init.d/masq
 +
/etc/init.d/masq restart
 +
 +
Check your change is working
 +
 +
====mysql====
 +
 +
Q) Is slaving SME's MySQL server for replication possible?  Is binary logging possible?  If so, do you edit the my.cnf file or some file to initiate binary logging?
 +
 +
A) First step is to go to the mysql web site and research what you want to do, see http://dev.mysql.com/doc/
 +
 +
When you find out what needs to be added to the /etc/my.cnf file, you can then make appropriate changes via a sme server custom template.
 +
 +
Examine the template fragments in /etc/e-smith/templates/etc/my.cnf
 +
 +
Determine which fragment your revised code needs to go into. See the 000readme fragment for info.
 +
 +
If no fragment is suitable you will need to create a new fragment. In the following example replace 005mysql with the appropriate existing or new fragment name.
 +
 +
Let's say you wish to modify the /etc/e-smith/templates/etc/my.cnf/005mysqld
 +
 +
Create a new directory and copy the existing template to the custom template tree (or create a new custom template)
 +
mkdir -p /etc/e-smith/templates-custom/etc/my.cnf/
 +
cp /etc/e-smith/templates/etc/my.cnf/005mysqld /etc/e-smith/templates-custom/etc/my.cnf/005mysqld
 +
Edit and make your required additions & changes. This is where you add the changes determined from the mysql documentation.
 +
nano -w /etc/e-smith/templates-custom/etc/my.cnf/005mysqld
 +
Save and exit
 +
Ctrl o
 +
Ctrl x
 +
Expand template and restart mysqld
 +
expand-template /etc/my.cnf
 +
sv t /service/mysqld
 +
Check status of the service
 +
sv s /service/mysqld
 +
 +
In this particular example there appears to be a requirement to share the mysql databases with LAN (local) or WAN (external) users. To achieve this you may need to change access permissions to your mysql databases, refer
 +
http://wiki.contribs.org/SME_Server:Documentation:FAQ#Access_MySQL_from_the_local_network
 +
http://wiki.contribs.org/SME_Server:Documentation:FAQ#Access_MySQL_from_a_remote_network
 +
http://wiki.contribs.org/SME_Server:Documentation:FAQ#Create_MySQL_user.28s.29_with_access_from_other_computers
 +
 +
 +
Check your changes are working
 +
 +
Removal
 +
To remove these custom changes you delete the custom template, expand the template and then restart the service, as follows
 +
rm /etc/e-smith/templates-custom/etc/my.cnf/005mysqld
 +
expand-template /etc/my.cnf
 +
sv t /service/mysqld
 +
Check status of the service
 +
sv s /service/mysqld
    
====php.ini====
 
====php.ini====
Line 58: Line 173:  
   
 
   
 
Copy the fragment to the custom template tree
 
Copy the fragment to the custom template tree
 +
mkdir -p /etc/e-smith/templates-custom/etc/php.ini
 
  cp /etc/e-smith/templates/etc/php.ini/40DataHandling /etc/e-smith/templates-custom/etc/php.ini/40DataHandling
 
  cp /etc/e-smith/templates/etc/php.ini/40DataHandling /etc/e-smith/templates-custom/etc/php.ini/40DataHandling
 
Edit the fragment and make your required changes
 
Edit the fragment and make your required changes
  pico -w /etc/e-smith/templates-custom/etc/php.ini/40DataHandling
+
  nano -w /etc/e-smith/templates-custom/etc/php.ini/40DataHandling
 
Save changes and exit (press the following keys together)
 
Save changes and exit (press the following keys together)
 
  Ctrl o
 
  Ctrl o
Line 69: Line 185:     
Examine /etc/php.ini to see that your changes have been created.
 
Examine /etc/php.ini to see that your changes have been created.
 +
 +
 +
====httpd.conf====
 +
 +
This example comes from a forum post at http://forums.contribs.org/index.php/topic,40336.0.html where a user asks how to redirect the "404 page not found rule" to a php file.
 +
 +
Make a custom template folder
 +
mkdir -p /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
 +
 +
Edit the template fragment with vi or nano
 +
cd /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
 +
nano S85ErrorPages
 +
and add the following text
 +
# Add custom error pages here
 +
ErrorDocument 404 /notfound.html
 +
 +
Save & exit from vi or nano
 +
Ctrl c
 +
Ctrl x
 +
 +
Expand template & restart service
 +
expand-template /etc/httpd/conf/httpd.conf
 +
sv t /service/httpd-e-smith
 +
 +
Using your favourite html editor, create a suitable web page & save it in the Primary/html ibay (or otherwise applicable ibay) with the filename of notfound.html
 +
 +
Then open your browser and type in an incorrect URL (making sure the domain is valid) eg
 +
http://www.mydomain.com/dunno
 +
and your new error page should be displayed.
 +
 +
If custom error pages are required for virtual domains, create a new html error page for each domain and save it in the html folder of the appropriate ibay.
 +
 +
This concept can also apply to other common error document pages such as
 +
 +
400 Bad Request
 +
401 Unauthorized
 +
403 Forbidden
 +
 +
These errors can be catered for by appropriate lines in the template fragment to point to the particular pages.
 +
 +
A full list of error codes can be found at http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
 +
 +
 +
====smb.conf====
 +
 +
This example comes from a forum post at http://forums.contribs.org/index.php/topic,49238.0.html where a user asks how to enable domain login to SME8 server from Windows 98 workstations,
 +
 +
and is based on advice from http://ubuntuforums.org/showthread.php?t=1617097
 +
 +
The SME server template fragments were examined & it was determined that the most suitable for the requirement was /etc/e-smith/templates/etc/smb.conf/11lanmanPasswords
 +
 +
Make a custom template folder
 +
cp /etc/e-smith/templates/etc/smb.conf/11lanmanPasswords /etc/e-smith/custom-templates/etc/smb.conf/
 +
 +
Edit the template fragment with vi, nano or nano
 +
cd /etc/e-smith/custom-templates/etc/smb.conf
 +
nano 11lanmanPasswords
 +
 +
and change the contents to the following code (in this example the perl code shown will allow parameters to be controlled by db commands rather than hard coding the parameters as text into the fragment)
 +
{
 +
$OUT .= "lanman auth = $smb{'LanManPasswords'}\n" if $smb{'LanManPasswords'};
 +
$OUT .= "client lanman auth = $smb{'ClientLanManPasswords'}\n" if $smb{'ClientLanManPasswords'};
 +
$OUT .= "client plaintext auth = $smb{'ClientPlaintextPasswords'}\n" if $smb{'ClientPlaintextPasswords'};
 +
}
 +
 +
Save & exit from nano
 +
Ctrl c
 +
Ctrl x
 +
 +
Then check & note current settings
 +
config show smb
 +
 +
Then issue
 +
config setprop smb LanManPasswords yes
 +
config setprop smb ClientLanManPasswords yes
 +
config setprop smb ClientPlaintextPasswords yes
 +
 +
Expand template & restart service (both included in the one signal-event command)
 +
  signal-event workgroup-update
 +
 +
Then review settings
 +
config show smb
 +
 +
Then manually check /etc/samba/smb.conf to see all changes & settings are present eg
 +
cat /etc/samba/smb.conf
 +
 +
Additional steps are required to modify passwords for Windows 98 users, from this post http://ubuntuforums.org/showthread.php?t=1617097
 +
 +
Re input passwords for every Windows 98 user (where username is the sme user who is logging into any Windows 98 workstation)
 +
smbpasswd -a username
 +
Then every Windows 98 user should log out and then log in again on their Windows 98 workstations (to pick up the changes on the server & allow successful login)
 +
       
More examples to be added to this section
 
More examples to be added to this section
 +
 +
===Quick steps & tips===
 +
 +
From http://forums.contribs.org/index.php/topic,45855.0.html
 +
 +
In order to override a SME template, the filename in .../templates-custom/... should to be identical to the filename in .../templates/....
 +
 +
Here's how to go about creating a custom template:
 +
 +
# Identify the service performing the task I want to customize
 +
# Identify the configuration file that needs to be customized
 +
# Change the config file manually
 +
# Restart the affected service
 +
# Verify that restarting the service did not return the config file to the original configuration (dnscache, for example, regenerates .../dnscache/root/servers each time the service is restarted)
 +
# Verify that the change introduced, fixes the problem I am addressing
 +
# Locate the default template fragment that generates the piece of the config file I want to modify
 +
# Copy the default template fragment into the appropriate .../templates-custom/... folder tree
 +
# Edit the .../templates-custom/... copy of the template fragment
 +
# Use expand-template to regenerate the target config file
 +
# Verify (using file date and time, or by using a slightly different value for the new parameter than was used in step 3) that the config file now contains the output generated by the new custom template fragement.
 +
# Re-test
 +
# Document the operation in the wiki if it seems to me that the info would be useful to others
 +
 +
Not every config option of every program is templated; for example, there is no template (that I can find) to control /var/service/qpsmtpd/config.
 +
 +
Not every template is in the location you might expect (.../qpsmtpd/peers/0 is built using the template fragments in .../qpsmtpd/config/plugins due to the instructions in .../templates.metadata/...).
 +
 +
Not every function is controlled by only one template (or config file) - email attachment size, for example, is affected by settings in qmail, qpsmtpd, php and clamd.
 +
 +
Finally, template fragments are processed alpha-numerically - so be sure that your customizations are inserted into the target config file in a sensible location.
 +
 +
 +
===Detailed generic troubleshooting & configuration steps===
 +
 +
From http://forums.contribs.org/index.php/topic,48300.msg239719.html#msg239719
 +
 +
This article refers to modifying a wordpress installation, but can be applied to any installed web application.
 +
 +
Here is a process that can be followed when trying to reverse-engineer a situation with a template or db setting affecting a website:
 +
 +
 +
Edit /etc/httpd/conf/httpd.conf directly.
 +
 +
locate the area that needs to be changed
 +
 +
insert the required commands
 +
 +
restart the web server using
 +
sv t httpd-e-smith
 +
 +
test
 +
 +
If something is broken, then return to the start (by resetting defaults) using:
 +
expand-template /etc/httpd/conf/httpd.conf; sv t httpd-e-smith
 +
 +
If the problem is fixed by the temporary config file changes, then identify the template fragment that generates the section that needs to be modified:
 +
cd /etc/e-smith/templates/etc/httpd/conf/httpd.conf
 +
grep -ril <some text near temporary change> *
 +
 +
In the above grep command, replace <some text near temporary change> with the text you are looking for.
 +
 +
 +
Then examine the files listed to see if the required change can be made using a db variable, or made via a custom template fragment. You will need to have a moderate understanding of the template/fragment code to determine this, ask on the forum if unsure or read the Developers Manual.
 +
 +
 +
If nothing is returned, repeat the search in /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf.
 +
 +
If the required changes are not supported by using a db variable, then create a custom template fragment:
 +
mkdir -p /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
 +
cd /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
 +
cp /etc/e-smith/templates/etc/httpd/conf/httpd.conf/<TheFileINeedToCustomize> .
 +
(note the trailing space and dot at the end of the last line).
 +
 +
Now edit the "custom" template fragment created, and those contents will be used instead of the default template fragment used when the affected file (/etc/httpd/conf/httpd.conf) is generated using 'expand-template'.
 +
 +
Some templates are inserted as literal text into the output files, and some templates are actually running perl code to generate the output text.  The perl templates will include braces ("{" and "}") and will likely contain lines beginning with [blue]$OUT .= "blah, blah, blah";[/blue].  If the template you've decided to copy includes perl code, you will need to write perl code to create your new output or place your changes after the final closing brace ("}") of the perl commands.
 +
 +
After making the changes:
 +
expand-template /etc/httpd/conf/httpd.conf; sv t httpd-e-smith
 +
 +
If the changes have broken something:
 +
cd /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
 +
rm <TheFileINeedToCustomize>
 +
expand-template /etc/httpd/conf/httpd.conf; sv t httpd-e-smith
 +
 +
 +
It is also useful to create a file to display your PHP version information:
 +
 +
cd /path/to/wordpress
 +
(insert path to your application)
 +
echo '<?php phpinfo(); ?>
 +
' > pi.php
 +
 +
Now browse to http://wordpress.url/pi.php (or your applications URL) and you should get a long listing of detailed information about the specific PHP that is invoked when running php from your wordpress or application folder.
 +
 +
Having phpinfo() sitting around on your server may introduce a security risk, so remove the file when finished troubleshooting.
    
===References===
 
===References===
Line 90: Line 394:  
----
 
----
 
[[Category:Howto]]
 
[[Category:Howto]]
 +
[[Category:Developer]]

Navigation menu