← Back to branch summary

~statik/ubuntu/maverick/erlang/erlang-merge-testing

« back to all changes in this revision

Viewing changes to lib/inets/doc/archive/includes.txt

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-05-01 10:14:38 UTC
  • mfrom: (3.1.4 sid)
  • Revision ID: james.westby@ubuntu.com-20090501101438-6qlr6rsdxgyzrg2z
Tags: 1:13.b-dfsg-2
* Cleaned up patches: removed unneeded patch which helped to support
  different SCTP library versions, made sure that changes for m68k
  architecture applied only when building on this architecture.
* Removed duplicated information from binary packages descriptions.
* Don't require libsctp-dev build-dependency on solaris-i386 architecture
  which allows to build Erlang on Nexenta (thanks to Tim Spriggs for
  the suggestion).

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/inets/doc/archive/includes.txt
 
1
  Server Side Includes (SSI)
 
2
 
 
3
NCSA HTTPd allows users to create documents which provide simple information
 
4
to clients on the fly. Such information can include the current date, the
 
5
file's last modification date, and the size or last modification of other
 
6
files. In its more advanced usage, it can provide a powerful interface to
 
7
CGI and /bin/sh programs.
 
8
 
 
9
   * SSI Issues
 
10
   * SSI Setup
 
11
   * Converting INC SRV to SSI
 
12
   * The SSI Format
 
13
   * SSI Environment Variables
 
14
 
 
15
------------------------------------------------------------------------
 
16
 
 
17
SSI Issues
 
18
 
 
19
Having the server parse documents is a double edged sword. It can be costly
 
20
for heavily loaded servers to perform parsing of files while sending them.
 
21
Further, it can be considered a security risk to have average users
 
22
executing commands as the server's User. If you disable the exec option,
 
23
this danger is mitigated, but the performance issue remains. You should
 
24
consider these items carefully before activating server-side includes on
 
25
your server.
 
26
 
 
27
------------------------------------------------------------------------
 
28
 
 
29
SSI Setup
 
30
 
 
31
First, you should decide which directories you want to allow Includes in.
 
32
Most likely this will not include users' home directories or directories you
 
33
do not trust. You should then decide, of the directories you are allowing
 
34
includes in, which directories are safe enough to use exec in.
 
35
 
 
36
For the directories in which you want to fully enable includes, you need to
 
37
use the Options directive to turn on the option Includes. Similarly for the
 
38
directories you want crippled (no exec) includes, you should use the option
 
39
IncludesNOEXEC. In any directory you want to disable includes, use the
 
40
Options directive without either option.
 
41
 
 
42
Next, you need to tell the server what filename extension you are using for
 
43
the parsed files. These files, while very similar to HTML, are not HTML and
 
44
are thus not treated the same. Internally, the server uses the magic MIME
 
45
type text/x-server-parsed-html to identify parsed documents. It will then
 
46
perform a format conversion to change these files into HTML for the client.
 
47
To tell the server which extension you want to use for parsed files, use the
 
48
AddType directive. For instance:
 
49
 
 
50
AddType text/x-server-parsed-html .shtml
 
51
 
 
52
This makes any file ending with .shtml a parsed file. Alternatively, if you
 
53
don't care about the performance hit of having all .html files parsed, you
 
54
could use:
 
55
 
 
56
AddType text/x-server-parsed-html .html
 
57
 
 
58
This would make the server parse all .html files.
 
59
 
 
60
------------------------------------------------------------------------
 
61
 
 
62
Converting your old INC SRV documents to the SSI Format
 
63
 
 
64
You should use the program inc2shtml in the support subdirectory of the
 
65
HTTPd distribution to translate your documents from HTTPd 1.1 and earlier to
 
66
the new format. Usage is simple: inc2shtml file.html > file.shtml.
 
67
 
 
68
------------------------------------------------------------------------
 
69
 
 
70
The SSI Format
 
71
 
 
72
All directives to the server are formatted as SGML comments within the
 
73
document. This is in case the document should ever find itself in the
 
74
client's hands unparsed. Each directive has the following format:
 
75
 
 
76
<!--#command tag1="value1" tag2="value2" -->
 
77
 
 
78
Each command takes different arguments, most only accept one tag at a time.
 
79
Here is a breakdown of the commands and their associated tags:
 
80
 
 
81
   * config
 
82
 
 
83
     The config directive controls various aspects of the file parsing.
 
84
     There are two valid tags:
 
85
 
 
86
        o errmsg controls what message is sent back to the client if an
 
87
          error includes while parsing the document. When an error occurs,
 
88
          it is logged in the server's error log.
 
89
 
 
90
        o timefmt gives the server a new format to use when providing dates.
 
91
          This is a string compatible with the strftime library call under
 
92
          most versions of UNIX.
 
93
 
 
94
        o sizefmt determines the formatting to be used when displaying the
 
95
          size of a file. Valid choices are bytes, for a formatted byte
 
96
          count (formatted as 1,234,567), or abbrev for an abbreviated
 
97
          version displaying the number of kilobytes or megabytes the file
 
98
          occupies.
 
99
 
 
100
   * include
 
101
 
 
102
     include will insert the text of a document into the parsed document.
 
103
     Any included file is subject to the usual access control. This command
 
104
     accepts two tags:
 
105
 
 
106
        o virtual gives a virtual path to a document on the server. You must
 
107
          access a normal file this way, you cannot access a CGI script in
 
108
          this fashion. You can, however, access another parsed document.
 
109
 
 
110
        o file gives a pathname relative to the current directory. ../
 
111
          cannot be used in this pathname, nor can absolute paths be used.
 
112
          As above, you can send other parsed documents, but you cannot send
 
113
          CGI scripts.
 
114
 
 
115
   * echo prints the value of one of the include variables (defined below).
 
116
     Any dates are printed subject to the currently configured timefmt. The
 
117
     only valid tag to this command is var, whose value is the name of the
 
118
     variable you wish to echo.
 
119
 
 
120
   * fsize prints the size of the specified file. Valid tags are the same as
 
121
     with the include command. The resulting format of this command is
 
122
     subject to the sizefmt parameter to the config command.
 
123
 
 
124
   * flastmod prints the last modification date of the specified file,
 
125
     subject to the formatting preference given by the timefmt parameter to
 
126
     config. Valid tags are the same as with the include command.
 
127
 
 
128
   * exec executes a given shell command or CGI script. It must be activated
 
129
     to be used. Valid tags are:
 
130
 
 
131
        o cmd will execute the given string using /bin/sh. All of the
 
132
          variables defined below are defined, and can be used in the
 
133
          command.
 
134
 
 
135
        o cgi will execute the given virtual path to a CGI script and
 
136
          include its output. The server does not perform error checking to
 
137
          make sure your script didn't output horrible things like a GIF, so
 
138
          be careful. It will, however, interpret any URL Location: header
 
139
          and translate it into an HTML anchor.
 
140
 
 
141
------------------------------------------------------------------------
 
142
 
 
143
SSI Environment Variables
 
144
 
 
145
A number of variables are made available to parsed documents. In addition to
 
146
the CGI variable set, the following variables are made available:
 
147
 
 
148
   * DOCUMENT_NAME: The current filename.
 
149
 
 
150
   * DOCUMENT_URI: The virtual path to this document (such as
 
151
     /docs/tutorials/foo.shtml).
 
152
 
 
153
   * QUERY_STRING_UNESCAPED: The unescaped version of any search query the
 
154
     client sent, with all shell-special characters escaped with \.
 
155
 
 
156
   * DATE_LOCAL: The current date, local time zone. Subject to the timefmt
 
157
     parameter to the config command.
 
158
 
 
159
   * DATE_GMT: Same as DATE_LOCAL but in Greenwich mean time.
 
160
 
 
161
   * LAST_MODIFIED: The last modification date of the current document.
 
162
     Subject to timefmt like the others.
 
163
 
 
164
------------------------------------------------------------------------
 
165
 [Back]   Return to tutorial index
 
166
 
 
167
------------------------------------------------------------------------
 
168
NCSA HTTPd Development Team / httpd@ncsa.uiuc.edu / 9-28-95