Return to tailoring.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/tailoring.tex, revision 1.1

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter      {The ISODE Tailoring File}\label{isotailor}
        !             4: The file \file{isotailor} in the ISODE \verb"ETCDIR" directory
        !             5: (usually \file{/usr/etc/})
        !             6: contains a simple run-time configuration
        !             7: mechanism for programs loaded with the \verb"-lisode" library.
        !             8: 
        !             9: The file itself is an ordinary ASCII text file containing information
        !            10: regarding the known tailoring options.
        !            11: Each line contains the option's name, a colon, the option's value, and a
        !            12: newline.
        !            13: The sharp character (`\verb"#"') at the beginning of a line indicates a
        !            14: commentary line.
        !            15: 
        !            16: \section      {Tailor Variables}
        !            17: The options available,
        !            18: along with default values and a description of their meanings,
        !            19: are now described.
        !            20: 
        !            21: \subsection    {Local Environment Tailoring}
        !            22: \begin{describe}
        !            23: \item[\verb"localname":] The name of the localhost.
        !            24: If not set,
        !            25: depending on the TCP/IP implementation you are running,
        !            26: the system will be queried for this value.
        !            27: 
        !            28: \item[\verb"binpath":] Where user programs are found.
        !            29: 
        !            30: \item[\verb"sbinpath":] Where system programs are bound.
        !            31: 
        !            32: \item[\verb"etcpath":] Where configuration files are found.
        !            33: \end{describe}
        !            34: 
        !            35: \vspace{0.1in}         %%% yikes!
        !            36: \begin{center}\em
        !            37: (continued on the next page)
        !            38: \end{center}
        !            39: \newpage
        !            40: 
        !            41: \subsection    {Logging Tailoring}
        !            42: \begin{describe}
        !            43: \item[\verb"logpath":] Where log files are found.
        !            44: 
        !            45: \item[\em xyz\/\verb"level":] The debugging level for the {\em xyz\/}
        !            46: module,
        !            47: defaulting to \verb"none".
        !            48: \[\begin{tabular}{|l|l|}
        !            49: \hline
        !            50:     \multicolumn{1}{|c|}{\bf Option}&
        !            51:                \multicolumn{1}{c|}{\bf Module}\\
        !            52: \hline
        !            53:     \tt compatlevel&   \man libicompat(3n)\\
        !            54:     \tt addrlevel&     various\\
        !            55:     \tt tsaplevel&     \man libtsap(3n)\\
        !            56:     \tt ssaplevel&     \man libssap(3n)\\
        !            57:     \tt psaplevel&     \man libpsap(3)\\
        !            58:     \tt psap2level&    \man libpsap2(3n)\\
        !            59:     \tt acsaplevel&    \man libacsap(3n)\\
        !            60:     \tt rtsaplevel&    \man librtsap(3n)\\
        !            61:     \tt rosaplevel&    \man librosap(3n)\\
        !            62: \hline
        !            63: \end{tabular}\]
        !            64: Options are seperated by whitespace.
        !            65: The debugging options available are:
        !            66: \begin{describe}
        !            67: \item[\verb"fatal":] fatal errors;
        !            68: 
        !            69: \item[\verb"exceptions":] exceptional events;
        !            70: 
        !            71: \item[\verb"notice":] informational notices;
        !            72: 
        !            73: \item[\verb"pdus":] {\em xyz\/}PDU printing;
        !            74: 
        !            75: \item[\verb"trace":] program tracing;
        !            76: 
        !            77: \item[\verb"debug":] full debugging
        !            78: (not fully defined at this point);
        !            79: and,
        !            80: 
        !            81: \item[\verb"all":] all of the above.
        !            82: \end{describe}
        !            83: Logging of levels other than \verb"fatal",
        !            84: \verb"exceptions", or \verb"notice" are subject
        !            85: to conditional compilation
        !            86: (the \verb"-DDEBUG" option must be used during compilation).
        !            87: 
        !            88: \item[\em xyz\/\verb"file":] The file to be used for {\em xyz\/}PDU tracing.
        !            89: The file is written in append mode.
        !            90: If the filename supplied is \arg"-" (a single dash),
        !            91: then the diagnostic output is used instead.
        !            92: \[\begin{tabular}{|l|l|l|}
        !            93: \hline
        !            94:     \multicolumn{1}{|c|}{\bf Option}&
        !            95:                \multicolumn{1}{c|}{\bf Default}&
        !            96:                \multicolumn{1}{c|}{\bf Module}\\
        !            97: \hline
        !            98:     \tt compatfile&    \tt \%d.log&    \man libicompat(3n)\\
        !            99:     \tt addrfile&      \tt \%d.log&    various\\
        !           100:     \tt tsapfile&      \tt \%d.tpkt&   \man libtsap(3n)\\
        !           101:     \tt ssapfile&      \tt \%d.spkt&   \man libssap(3n)\\
        !           102:     \tt psapfile&      \tt \%d.pe&     \man libpsap(3)\\
        !           103:     \tt psap2file&     \tt \%d.ppkt&   \man libpsap2(3n)\\
        !           104:     \tt acsapfile&     \tt \%d.acpkt&  \man libacsap(3n)\\
        !           105:     \tt rtsapfile&     \tt \%d.rtpkt&  \man librtsap(3n)\\
        !           106:     \tt rosapfile&     \tt \%d.ropkt&  \man librosap(3n)\\
        !           107: \hline
        !           108: \end{tabular}\]
        !           109: The \man getpid(2) call is used to supply the value for \verb"%d".
        !           110: \end{describe}
        !           111: 
        !           112: \subsection    {Directory Services Tailoring}\label{dse:tailor}
        !           113: \begin{describe}
        !           114: \item[\verb"ns\_enable":] enables use of a ``user-friendly nameservice''
        !           115: to perform name/address resolution.
        !           116: This takes the value either \verb+"on"+ or \verb+"off"+.
        !           117: If \verb+"on"+,
        !           118: then an OSI Directory-based service will be use.
        !           119: If the nameservice lookup fails,
        !           120: the stub-directory will be used as a fallback.
        !           121: 
        !           122: \item[\verb"ns\_address":] the transport address of the nameservice.
        !           123: It is specified using the ISODE ``string'' format,
        !           124: e.g.,
        !           125: \begin{quote}\small\begin{verbatim}
        !           126: Internet=wp.psi.com+17006
        !           127: \end{verbatim}\end{quote}
        !           128: which indicates that the nameservice lives in the TCP/IP communications domain
        !           129: on TCP port \verb"17006" at host \verb"wp.psi.com".
        !           130: The nameservice is accessed via the OSI CO-mode transport service,
        !           131: so other kinds of addresses (e.g., X.25 addresses can be used as well).
        !           132: \end{describe}
        !           133: 
        !           134: \subsection    {Transport Switch Tailoring}
        !           135: The use of these variables is more usefully described in Chapter~\ref{tswitch}.
        !           136: \begin{describe}
        !           137: \item[\verb"ts\_stacks":] Specifies which configured TS-stacks are
        !           138: enabled.
        !           139: This is useful when multiple machines (with different interfaces)
        !           140: share the same executables.
        !           141: Options are seperated by whitespace:
        !           142: \begin{describe}
        !           143: \item[\verb"tcp":] RFC1006 over TCP/IP;
        !           144: 
        !           145: \item[\verb"x25":] TP0 over X.25;
        !           146: 
        !           147: \item[\verb"cons":] TP0 over CONS;
        !           148: 
        !           149: \item[\verb"bridge":] TP0 over the TP0--bridge;
        !           150: 
        !           151: \item[\verb"tp4":] TP4 over CLNP;
        !           152: and,
        !           153: 
        !           154: \item[\verb"all":] all of the above.
        !           155: \end{describe}
        !           156: Using this method,
        !           157: the \file{isotailor} file is a normally symbolic link to
        !           158: \file{/private/etc/isotailor}.
        !           159: 
        !           160: \item[\verb"ts\_interim":] Defines new OSI communities.
        !           161: Each community is defined by a macro in the \file isomacros(5) file.
        !           162: 
        !           163: \item[\verb"ts\_communities":] Specifies which OSI communities are attached
        !           164: (either directly or through a transport-service bridge).
        !           165: Options are seperated by whitespace:
        !           166: \begin{describe}
        !           167: \item[\verb"int-x25":] International X.25;
        !           168: 
        !           169: \item[\verb"janet":] UK JANET;
        !           170: 
        !           171: \item[\verb"internet":] the capital-I Internet;
        !           172: 
        !           173: \item[\verb"realns":] OSI Internet (ha, ha);
        !           174: 
        !           175: \item[\verb"localTCP":] the TCP loopback address;
        !           176: and,
        !           177: 
        !           178: \item[\verb"all":] all of the above OSI communities, along with those
        !           179: communities defined by the \verb"ts_interim" variable;
        !           180: \end{describe}
        !           181: For example,
        !           182: a site with an X.25 connection might be attached to the International X.25
        !           183: network, but not the JANET.
        !           184: Thus \verb"ts_stacks" would include ``x25'',
        !           185: and \verb"ts_communities" would include ``int-x25'' but not ``janet''.
        !           186: 
        !           187: Note that the ordering of communities is important:
        !           188: network addresses will be tried in the order that their respective
        !           189: communities are listed with this variable.
        !           190: 
        !           191: \item[\verb"default\_nsap\_community":] the default community to be
        !           192: used for NSAP addresses.
        !           193: 
        !           194: \item[\verb"default\_x25\_community":] the default community to be
        !           195: used for X.25 (DTE) addresses.
        !           196: 
        !           197: \item[\verb"default\_tcp\_community":] the default community to be
        !           198: used for TCP (RFC1006) addresses.
        !           199: \end{describe}
        !           200: 
        !           201: \subsubsection{Transport-Service Bridge}
        !           202: There are two variables that can be specified.
        !           203: One is used on hosts making use of the TS-bridge,
        !           204: the other is used by hosts which run the TS-bridge:
        !           205: \begin{describe}
        !           206: \item[\verb|tsb\_communities|] A list of pairs of values.
        !           207: The first of each value should be a community name as defined in
        !           208: the \verb"ts_communities" variable.
        !           209: The second value of the pair should be a presentation address using the ISODE
        !           210: ``string'' format.
        !           211: When a call is to be placed and the network corresponds to one
        !           212: of the communities given here, then a call through the TS-bridge given in
        !           213: the second variable will be made automatically.
        !           214: 
        !           215: \item[\verb|tsb\_default\_address|] This variable contains a string encoded
        !           216: presentation address which the TS-bridge will listen on by default.
        !           217: This should normally consist of a set of network addresses with no selectors
        !           218: present.
        !           219: \end{describe}
        !           220: Consider the case of a host with access to both the Internet and the
        !           221: International X.25 network.
        !           222: This host might have this entry in its \file{isotailor} file:
        !           223: \begin{quote}\tiny\begin{verbatim}
        !           224: tsb_default_address: Internet=sheriff+17004\|Int-X25(80)=23426020017299+PID+03018000
        !           225: \end{verbatim}\end{quote}
        !           226: This tells the TS-bridge to listen on two network endpoints.
        !           227: Hosts in the Internet community wishing to reach the International
        !           228: X.25 community would have this entry in their \file{isotailor} file:
        !           229: \begin{quote}\smaller\begin{verbatim}
        !           230: tsb_communities: int-x25 Internet=sheriff+17004
        !           231: \end{verbatim}\end{quote}
        !           232: Similarly,
        !           233: hosts in the International X.25 community wishing to reach the
        !           234: Internet community, would have the entry:
        !           235: \begin{quote}\smaller\begin{verbatim}
        !           236: tsb_communities: internet Int-X25(80)=23426020017299+PID+03018000
        !           237: \end{verbatim}\end{quote}
        !           238: 
        !           239: \subsection{Interface Specific Tailoring}
        !           240: Some network implementations used by ISODE require ISODE to be
        !           241: tailored for their correct use.
        !           242: 
        !           243: \subsubsection{General X.25 Tailoring}
        !           244: The following tailoring variables are generally applicable to
        !           245: X.25 networks.
        !           246: \begin{describe}
        !           247: \item[\verb"x25\_local\_dte"] It is normally
        !           248: necessary for ISODE to know it's local DTE
        !           249: address.
        !           250: This variable is used to set this.
        !           251: The default is empty, i.e. do not set a calling address in call
        !           252: requests.
        !           253: 
        !           254: \item[\verb"x25\_local\_pid"] It is normally
        !           255: necessary for ISODE to know the X.25 protocol ID to listen on
        !           256: This is specified in hex-notation,
        !           257: e.g., \verb"03010100".
        !           258: 
        !           259: \item[\verb"x25\_intl\_zero"] Some Public Data Networks
        !           260: require that X.121 addresses be
        !           261: modified before being conveyed.
        !           262: If this variable has the value \verb"on" then any addresses
        !           263: with a non-local DNIC will have a leading zero appended.
        !           264: 
        !           265: \item[\verb"x25\_strip\_dnic"] If this variable has
        !           266: the value \verb"on" then any address with
        !           267: a local DNIC will have this removed.
        !           268: 
        !           269: \item[\verb"x25\_dnic\_prefix"] If you use either or both of the
        !           270: preceding two mechanisms then you must use this variable to
        !           271: inform ISODE of the local DNIC for your host.
        !           272: 
        !           273: \item[\verb"x25level":]
        !           274: Defines the level of logging to be used for X.25 statistics logging.
        !           275: (At present, only \verb"notice" messages are generated.)
        !           276: 
        !           277: \item[\verb"x25file":]
        !           278: Defines the filename to be used for X.25 statistics logging.
        !           279: \end{describe}
        !           280: 
        !           281: \subsubsection{SunLink X.25}
        !           282: The following variables are currently only supported by the
        !           283: SunLink X.25 interface.
        !           284: They control the X.25 Facilities that are requested or accepted.
        !           285: \begin{describe}
        !           286: \item[\verb"reverse\_charge"]  If \verb"0" then don't
        !           287: request/allow (initiator/responder) reverse charging.
        !           288: If \verb"1" then request/allow reverse charging.
        !           289: 
        !           290: \item[\verb"recvpktsize"/\verb"sendpktsize"] Size of level 3 packets.
        !           291: Valid values are \verb"0" (default size),
        !           292: \verb"16", \verb"32", \verb"64", \verb"128",
        !           293: \verb"256", \verb"512", \verb"1024" (octets in decimal).
        !           294: 
        !           295: \item[\verb"recvwndsize"/\verb"sendwndsize"] Size of level 3 window.
        !           296: Valid values are \verb"0" (default window size),
        !           297: \verb"1"--\verb"7" or \verb"1"--\verb"127" (decimal).
        !           298: 
        !           299: \item[\verb"recvthruput"/\verb"sendthruput"] Send/receive throughput.
        !           300: \nopagebreak
        !           301: \begin{quote}
        !           302: \begin{tabbing}
        !           303: 100\=1200\hspace{2em}\=100\=\kill
        !           304: \verb"0"\> default throughput \\
        !           305: \verb"3"\> 75\> \verb"8"\> 2400 \\
        !           306: \verb"4"\> 150\> \verb"9"\> 4800 \\
        !           307: \verb"5"\> 300\> \verb"10"\> 9600 \\
        !           308: \verb"6"\> 600\> \verb"11"\> 19200 \\
        !           309: \verb"7"\> 1200\> \verb"12"\> 48000  \\
        !           310: \end{tabbing}
        !           311: \end{quote}
        !           312: Values in bps decimal.
        !           313: 
        !           314: \item[\verb"cug\_req"] If \verb"0" then don't use closed user group, if
        !           315: \verb"1" then use closed user group specified by
        !           316: \verb"cug_index".
        !           317: 
        !           318: \item[\verb"cug\_index"] Closed user group in decimal
        !           319: (\verb"00"--\verb"99").
        !           320: 
        !           321: \item[\verb"fast\_select\_type"] \verb"0" = don't use/allow fast
        !           322: select.
        !           323: \verb"1" = calling side --- only accept clear in response to
        !           324: fast select, called side --- send clear in response to fast
        !           325: select.
        !           326: % is any of this fast select stuff applicable to ISODE?
        !           327: \verb"2" = clear or accept is valid response to fast select.
        !           328: 
        !           329: \item[\verb"rpoa\_req"] If \verb"0" then don't request RPOA
        !           330: (Recognised Private Operating Agency) transit.
        !           331: If \verb"1" then request RPOA transit.
        !           332: 
        !           333: \item[\verb"rpoa"] If \verb"rpoa_req" is \verb"1" then this is
        !           334: RPOA transit group in decimal (\verb"0000"--\verb"9999").
        !           335: \end{describe}
        !           336: % actually cug_index and rpoa seem to be ignored in the current version
        !           337: See the SunLink X.25 Programmer's Manual for
        !           338: further explanations of these
        !           339: facilities.
        !           340: 
        !           341: \subsubsection{Camtec CCL}
        !           342: There is one tailoring variable for the Camtec X.25 when used
        !           343: with the socket abstraction.%
        !           344: \footnote{The old device level interface is no longer supported.}
        !           345: \begin{describe}
        !           346: \item[\verb"x25\_outgoing\_port"] selects the physical port on the
        !           347: Camtec card for outgoing calls.
        !           348: It may take the value \verb"A", \verb"B" or \verb"#".
        !           349: \verb"A" and \verb"B" are the X.121 WAN ports and \verb"#" is
        !           350: the IEEE 802.3 (Ethernet) port.
        !           351: Incoming calls will be accepted on any port.
        !           352: \end{describe}
        !           353: 
        !           354: \subsubsection{Bridge X.25}
        !           355: There are several tailorable variables that can specified for the
        !           356: bridge connection. These are:
        !           357: \begin{describe}
        !           358: \item[\verb|x25\_bridge\_host|]        selects the host that runs the
        !           359: tp0bridge being used. This should be a TCP accessible host.
        !           360: 
        !           361: \item[\verb|x25\_bridge\_port|]        selects the TCP port that the
        !           362: tp0bridge will be listening on. The default for this is port 146 (an
        !           363: internet assigned number), which should be defined in \verb|/etc/services|.
        !           364: 
        !           365: \item[\verb|x25\_bridge\_addr|]        the X.121 address of the remote host.
        !           366: 
        !           367: \item[\verb|x25\_bridge\_listen|]      the X.121 address that this host will
        !           368: be listening on for incoming calls via the bridge.
        !           369: 
        !           370: \item[\verb|x25\_bridge\_pid|] the protocol id used for listening
        !           371: along with the above address. This is a set of eight hex digits.
        !           372: 
        !           373: \item[\verb|x25\_bridge\_discrim|] selects the network layer to use.
        !           374: When attempting to place a call with the bridge code configured as
        !           375: well as real X.25, the string selects the interface to use. If the
        !           376: string is empty, the bridge will always be used. If it is set to
        !           377: ``--'' the bridge will not be used. If the string is anything else, it
        !           378: is compared against the initial portion of the called X.121 address.
        !           379: If there is a match then the bridge is used, otherwise the real
        !           380: interface is called.
        !           381: \end{describe}
        !           382: 
        !           383: \section      {Accessing the Tailoring File}
        !           384: The tailoring file is read usually when a program attempts or accepts its
        !           385: first connection.
        !           386: The \verb"-lisode" library does this by calling the routine
        !           387: \verb"isodetailor":
        !           388: \begin{quote}\index{isodetailor}\small\begin{verbatim}
        !           389: void    isodetailor (myname, wantuser)
        !           390: char   *myname;
        !           391: int     wantuser;
        !           392: \end{verbatim}\end{quote}
        !           393: The parameters to this procedure are:
        !           394: \begin{describe}
        !           395: \item[\verb"myname":] the name that the program was invoked with
        !           396: (used by the logging package described in Chapter~\ref{logging}); and,
        !           397: 
        !           398: \item[\verb"wantuser":] if non-zero,
        !           399: then a user-specific tailoring file,
        !           400: with the name \verb"~/.myname_tailor",
        !           401: should be consulted.
        !           402: \end{describe}
        !           403: Note that in order to ensure consistent logging it is {\bf critical\/} that
        !           404: the call to \verb"isodetailor" be the first call made to {\em any \/} of the
        !           405: ISODE routines.
        !           406: 
        !           407: To override the default location of the tailoring file,
        !           408: use the routine \verb"isodesetailor":
        !           409: \begin{quote}\index{isodesetailor}\small\begin{verbatim}
        !           410: char   *isodesetailor (file)
        !           411: char   *file;
        !           412: \end{verbatim}\end{quote}
        !           413: The parameter to this procedure is:
        !           414: \begin{describe}
        !           415: \item[\verb"file":] the filename to be used instead of the default.
        !           416: Future versions of this routine might act differently.
        !           417: \end{describe}
        !           418: The filename is interpreted relative to the \verb"-lisode" system area.
        !           419: To override this, specify a anchored pathname
        !           420: (e.g., on \unix/, one which starts with \verb"/" or \verb"./").
        !           421: The routine returns the name of the default tailoring file.
        !           422: 
        !           423: To set a tailoring variable from some other configuration file,
        !           424: the routines \verb"isodesetvar" and \verb"isodexport" are used:
        !           425: \begin{quote}\index{isodesetvar}\small\begin{verbatim}
        !           426: int     isodesetvar (name, value, dynamic)
        !           427: char   *name,
        !           428:        *value;
        !           429: int     dynamic;
        !           430: \end{verbatim}
        !           431: \end{quote}
        !           432: When this routine is invoked,
        !           433: it acts as though
        !           434: \begin{quote}\small\begin{verbatim}
        !           435: name: value
        !           436: \end{verbatim}\end{quote}
        !           437: was found in the tailoring file.
        !           438: The \verb"dynamic" parameter, if non-zero,
        !           439: indicates that \verb"value" may be freed if a subsequent
        !           440: call to \verb"isodesetvar" is made which overrides the previous value.
        !           441: 
        !           442: The \verb"isodexport" routine is called after one or more calls to
        !           443: \verb"isodesetvar",
        !           444: it performs any post-processing necessary to resynchronize the tailoring
        !           445: facilities.
        !           446: \begin{quote}\index{isodexport}\small\begin{verbatim}
        !           447: void    isodexport ()
        !           448: \end{verbatim}
        !           449: \end{quote}
        !           450: Thus,
        !           451: to read a private tailoring file,
        !           452: \verb"isodesetvar" should be called for each tailoring line.
        !           453: Then,
        !           454: \verb"isodexport" should be called once to resynchronize things.
        !           455: 
        !           456: Finally, it may be necessary to access files in the \verb"-lisode" system area.
        !           457: The routine \verb"isodefile" takes an filename and returns an anchored
        !           458: pathname.
        !           459: \begin{quote}\index{isodefile}\small\begin{verbatim}
        !           460: char   *isodefile (file, ispgm)
        !           461: char   *file;
        !           462: int    ispgm;
        !           463: \end{verbatim}\end{quote}
        !           464: The parameters to this procedure are:
        !           465: \begin{describe}
        !           466: \item[\verb"file":] the filename to be expanded;
        !           467: and,
        !           468: 
        !           469: \item[\verb"ispgm":] non-zero if the target file is an executable
        !           470: (otherwise it is a database of some kind).
        !           471: \end{describe}
        !           472: This routine is actually a macro which invokes the routine \verb"_isodefile":
        !           473: \begin{quote}\index{\_isodefile}\small\begin{verbatim}
        !           474: char   *_isodefile (path, file)
        !           475: char   *path,
        !           476:        *file;
        !           477: \end{verbatim}\end{quote}
        !           478: The parameters to this procedure are:
        !           479: \begin{describe}
        !           480: \item[\verb"path":] the directory where the filename should be expanded; and,
        !           481: 
        !           482: \item[\verb"file":] the filename to be expanded.
        !           483: \end{describe}
        !           484: 
        !           485: %%% \section  {Changes Since the Last Release}\label{compat:changes}
        !           486: %%% A brief summary of the major changes between v~\compatprevrsn/ and
        !           487: %%% v~\compatvrsn/ are now presented.
        !           488: %%% These are the user-visible changes only;
        !           489: %%% changes of a strictly internal nature are not discussed.
        !           490: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.