ssi

מאמר 11: SSI - המדריך השלם

11.1 פקודות

את התוצאות להלן ניתן להשיג באמצעות CGI scripts, Shell scripts או תוכניות
בשפת C, אך תוספות שרת ( SSI ) לרוב מבצעות את הנדרש במאמץ קטן הרבה יותר.
קובץ הקונפיגורציה לאתר זה הוא:

User webuser
Group webgroup
ServerName www.butterthlies.com
DocumentRoot /usr/www/site.ssi/htdocs
AccessConfig /dev/null
ResourceConfig /dev/null
AddHandler server-parsed shtml

שורת המפתח היא: AddHandler server-parsed shtml.

shtml היא המצאה של אפאצ'י והיא מהווה הרחבה לקבצים הרלוונטיים במסמכי htdocs. יש לחפש ב- error log אם הדברים אינם מתבצעים כהלכה. הודעות השגיאה המועברות ללקוח הן בהכרח בעלות מידע מצומצם כי סביר שמי שקורא אותם נמצא במרחק שלוש יבשות וממילא אינו יכול לעשות דבר.

הטריק הוא להכניס מחרוזות מיוחדות לתוך המסמכים שאפאצ'י יאתר, יזהה ויחליף בהודעות דינמיות. למחרוזות אלה יש צורה ייחודית ומכוונת כדי שלא יתבלבלו בינם לבין המחרוזות הרגילות.

תחביר של פקודה הוא: <-- ...element attribute=value attribute=value #--!>.

11.1.1 פקודת Config

פקודה זו קובעת היבטים שונים של החלוקה והניתוח - המאפיינים התקפים של פקודה זו הם:
1. errmsg - הערך הוא הודעה שנשלחת חזרה ללקוח אם מתרחשת שגיאה בעת החלוקה וניתוח.
2. sizefmt - הערך קובע באיזה פורמט יוצג גודל של קובץ (bytes - תצוגה בבתים; abbrev תצוגה בקילובית או מגהבית ).
3. timefmt - הערך הוא מחרוזת אשר תופעל ע"י רוטינת ספריית Strftime בהדפסת תאריכים.

11.1.2 פקודת echo

פקודה זו מדפיסה את אחד ממשתני ה- include. אם המשתנה אינו מוגדר, הוא מודפס כ- (none). כל תאריך שמודפס כפוף לקונפיגורציה הקיימת של timefmt.
המשתנה היחיד של פקודה זו הוא var וערכו הוא שם המשתנה להדפסה.

11.1.3 פקודת exec

פקודה זו מריצה פקודת shell או CGI script. ביטול פקודה זו מתבצע ע"י אופציית IncludeNOEXEC. המאפין בר תוקף הוא cgi.
cgi - הערך הוא נתיב יחסי ל- CGI script של URL. אם הנתיב אינו מתחיל ב - "/", מתייחסים אליו כאל נתיב יחסי למסמך הנוכחי. המסמך אליו מתייחס הנתיב נתפס ע"י השרת כ- CGI script, אפילו אם השרת לא היה מזהה אותו ככזה. אך, הספריה המכילה את ה- script חייבת לאפשר CGI scripts (בעזרת האופציה Script Alias או ExecCGI).

ה- CGI script מקבל את ה- PATH_INFO ומחרוזת השאילתה (QUERY_STRING) של הבקשה המקורית מהלקוח - אי אפשר לפרט אותם בנתיב ה- URL. ה- script יוכל להשתמש גם במשתני include וגם בסביבת CGI הסטנדרטית. אם ה- script מחזיר כותרת עליונה במקום פלט, זה מתורגם לעוגן HTML. אם האופציה NoExec Options מוגדרת בקובץ Config, לא ניתן להשתמש באופציה זו.
יש עדיפות לאלמנט virtual include על פני exec cgi.

11.1.4 פקודת cmd

השרת מריץ את המחרוזת הנתונה בעזרת bin/sh/ . הפקודה יכולה להכיל משתני include. אם NoExec Options מוגדרת בקובץ הקונפיגורציה, פקודה זו אינה פועלת.

11.1.5 פקודת fsize

פקודה זו מדפיסה את גודלו של קובץ מסוים, בכפוף למפרט הפורמט של . Sizefmt מאפייניו הם:
1. file - ערכו הוא נתיב, יחסית לספריה הכוללת את המסמך המחולק והמנותח.
2. virtual - ערכו הוא נתיב יחסי של URL למסמך המחולק והמנותח. אם אינו מתחיל ב - "/", הוא מפורש כנתיב יחסית למסמך הנוכחי.

11.1.6 פקודת flastmod

פקודה זו מדפיסה את תאריך העדכון האחרון של הקובץ, בכפוף להגדרת timefmt. מאפייניו זהים לפקודת fsize.

11.1.7 פקודת include

פקודה זו מכניסה את הטקסט של קובץ או מסמך נוסף לתוך הקובץ המנותח. כל קובץ אשר מתווסף באופן זה, כפוף לבקרת גישה רגילה. אם לספריה המכילה קובץ זה מוגדר IncludesNOEXEC, ואם הוספת המסמך גורמת להרצת תוכנית, הקובץ אינו מתווסף. כך מונעים הרצה של CGI scripts.

מאפיין מגדיר את מיקומו של המסמך. ההוספה מתבצעת עבור כל מאפיין של פקודת include.
המאפיינים התקפים הם:
1. file - ערכו של מאפיין זה הוא נתיב יחסי לספריה המכילה את המסמך המנותח. אסור שיכלול /.. או נתיבים אבסולוטיים (מוחלטים). תמיד יש להעדיף את המאפיין virtual על פני מאפיין זה.
2. virtual - כתובת URL יחסית למסמך המנותח. אסור שה- URL יכלול hostname; רק נתיב ומחרוזת שאילתא אופציונלית. אם הכתובת אינה מתחילה ב - "/", היא מובנת כנתיב יחסי למסמך הנוכחי. כתובת URL בנויה מערכו של המאפיין, והשרת מחזיר את אותו פלט שהיה מתקבל אם הלקוח היה מבקש את ה- URL. כך ניתן לקונן קבצים שמוסיפים באמצעות include. בשיטה זו עדיין ניתן להפעיל CGI scriptאפילו אם האופציה Options NoExec מוגדרת בקובץ הקונפיגורציה. ההגיון הוא שהלקוחות ממילא יכולים להפעיל את ה- CGI באמצעות שימוש ב- URL שלו כ- hot link, או הקלדתו בדפדפן ולכן לא נגרם נזק בשימוש בשיטה זו (להבדיל מ- cmd או exec).

11.2 file Size

פקודה ה - fsize מאפשרת לדווח על גודל הקובץ בתוך מסמך. הקובץ size.shtml הוא:

<!--#config errmsg="Bungled again!"-->
<!--#config sizefmt="bytes"-->
The size of this file is <!--#fsize file="size.shtml"--> bytes.
The size of another_file is <!--#fsize file="another_file"--> bytes.

השורה הראשונה נותנת הודעת שגיאה.
השורה השניה מגדירה שגודל הקובץ מוצג בבתים (abbrev במקום bytes יביא להצגה בקילובתים).
השורה השלישית מדפיסה את גודל size.shtml.
השורה הרביעית מדפיסה את גודלו של another_file.

פקודות config חייבות לבוא מעל פקודות אשר עשויות להשתמש בהן.
אפשר לכתוב =virtual במקום = file . virtual נותן את נתיב ה- URL יחסית למסמך המנותח. אם אינו מתחיל ב - "/", הוא מובן ככתובת יחסית למסמך הנוכחי.
יש להקפיד בתחביר - למשל רווחים בסוף מחרוזת גורמים לשגיאה. למשל:

The size of this file is <!--#fsize file="size.shtml   "--> bytes.
The size of this file is Bungled again! bytes

ללא שימוש בפקודת errmsg, היינו רואים:
...[an error occurred while processing this directive].... .

11.3 זמן עדכון הקובץ

ניתן לדווח על תאריך עדכון אחרון של קובץ בעזרת flastmod. אפשרות זו נותנת ללקוח התרשמות על מידת העדכון של הנתונים המוצגים בפניו. מאפיין timefmt קובע את פורמט הפלט (באלמנט config). הכללים למאפיין timefmt זהים לאלה שלפונקציית Strftime בשפת C של UNIX.

הקובץ time.shtml נותן את הדוגמא הבאה:

<!--#config errmsg="Bungled again!"-->
<!--#config timefmt="%A %B %C, the %jth day of the year, %S seconds since the Epoch"-->
The mod time of this file is <!--#flastmod virtual="size.shtml"-->
The mod time of another_file is <!--#flastmod virtual="another_file"-->

והפלט הוא:

The mod time of this file is Tuesday August 19, the 240th day of the year, 
  841162166 seconds since the Epoch The mod time of another_file is Friday August 19, 
     the 229th day of the year, 840194838 seconds since the Epoch

includes 11.4

נוכל להכניס קובץ אחד בתוך אחר באמצעות פקודת include בצורה הבאה:

<!--#config errmsg="Bungled again!"-->
This is some text in which we want to include text from another file:
<< <!--#include virtual="another_file"--> >>
That was it.

והפלט הוא:

This is some text in which we want to include text from another file:
<< This the stuff in 'another_file'. >>
That was it.

11.5 הרצת CGI

אנו יכולים להריץ CGI script מבלי להשתמש ב - SetHandler, AddHandler או ExecCGI.
הפקודה היא {exec{ cmd cgi:

<!--#config errmsg="Bungled again!"-->
We're now going to execute the file 'do_this'.
<< <!--#exec cmd="rubbish/do_this"--> >>
and now /usr/www/cgi-bin/mycgi.ok:
<< <!--#exec cmd="/usr/www/cgi-bin/mycgi.ok"--> >>
That was it.

ה- script do-this הוא: ls- l.

יש שני מאפיינים ל- exec: האחד הוא cgi והשני הוא cgi .cmd מריץ CGI script ואילו cmd משתמש ב- bin/sh :shell/.

הפלט הוא:

We're now going to execute the file 'do_this'. << >> and
              now /usr/www/cgi-bin/mycgi.ok: <<
Content-type: text/html GATEWAY_INTERFACE=CGI/1.1 REMOTE_HOST=192.168.123.1
DOCUMENT_URI=/exec.shtml REMOTE_ADDR=192.168.123.1 QUERY_STRING=
HTTP_USER_AGENT=Mozilla/3.0Gold (Win95; I)
DOCUMENT_ROOT=/usr/www/site.ssi/htdocs HTTP_ACCEPT=image/gif,
               image/x-xbitmap,
image/jpeg, image/pjpeg, */* SCRIPT_FILENAME=/usr/www/site.ssi/htdocs/
               exec.shtml
LAST_MODIFIED=Thursday, 12-Sep-96 16:34:49 DOCUMENT_NAME=exec.shtml
HTTP_HOST=192.168.123.2 SERVER_SOFTWARE=Apache/1.2-dev
HTTP_CONNECTION=Keep-Alive HTTP_COOKIE=Apache=192380845288358461
PATH=/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/bin HTTP_REFERER=
               http://192.168.123.2/
SERVER_PROTOCOL=HTTP/1.0 DATE_GMT=Monday, 14-Oct-96 10:21:00
DOCUMENT_PATH_INFO= REQUEST_METHOD=GET SERVER_ADMIN=[no address
given] SERVER_PORT=80 USER_NAME=root SCRIPT_NAME=/exec.shtml
SERVER_NAME=www.butterthlies.com DATE_LOCAL=Monday, 14-Oct-96 10:21:00 >>
That was it.

11.6 פקודת echo

ניתן להדפיס מספר משתני סביבה - DATE_GMT, DATE_LOCAL, DOCUMENT_NAME, DOCUMENT_URI LAST_MODIFIED.

הקובץ echo.shtml הוא:

Echoing the Document_URI <!--#echo var="DOCUMENT_URI"-->
Echoing the DATE_GMT <!--#echo var="DATE_GMT"-->

הפלט הוא:

Echoing the Document_URI /echo.shtml
Echoing the DATE_GMT Saturday, 17-Aug-96 07:50:31

11.7 פקודת XbitHack

זוהי אפשרות מיושנת לבצע תוספות שרת באופן אוטומטי אם הרשאת הביצוע מוגדרת בקובץ מסוים. הוא נועד להבטיח תאימות אחורנית. אם מוגדר ה- group execute bit, מוגדר לדפדפן זמן פקיעה ממושך.

11.8 XSSI

זוהי הרחבה לפקודות SSI הסטנדרטיות הזמינות במודול XSSI, אשר הפכה להיות חלק מתקן האפאצ'י החל מגרסה 1.2.

XSSI מוסיף ביחס ל- SSI את היכולות הבאות:
1. XSSI מאפשר משתנים בכל פקודות ה- SSI. למשל אפשר לקבל את תאריך עדכון
האחרון של המסמך הנוכחי בעזרת:
<--"tt><!--#flastmod file="$DOCUMENT_NAME>.
2. פקודת set מגדירה את המשתנים בתוך ה- SSI.
3. אפשר להשתמש בפקודות SSI if, else, elif, endif כדי להוסיף חלקי קובץ על פי
תנאים. למשל, ניתן לבדוק את המשתנה HTTP_USER_AGENT$ כדי לבדוק את סוג
הדפדפן, ופלטים שונים של HTML על פי יכולות הדפדפן.