Annotation of src/share/man/man7/script.7, Revision 1.6
1.6 ! joerg 1: .\" $NetBSD: script.7,v 1.5 2008/04/30 13:10:57 martin Exp $
1.1 perry 2: .\"
3: .\" Copyright (c) 2005 The NetBSD Foundation, Inc.
4: .\" All rights reserved.
5: .\"
6: .\" This document was originally contributed to The NetBSD Foundation
7: .\" by Perry E. Metzger of Metzger, Dowdeswell & Co. LLC.
8: .\"
9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28: .\" POSSIBILITY OF SUCH DAMAGE.
29: .\"
30: .Dd May 6, 2005
31: .Dt SCRIPT 7
32: .Os
33: .Sh NAME
34: .Nm script
35: .Nd interpreter script execution
36: .Sh DESCRIPTION
37: The system is capable of treating a text file containing commands
38: intended for an interpreter, such as
39: .Xr sh 1
40: or
41: .Xr awk 1 ,
42: as an executable program.
43: .Pp
44: An
45: .Dq interpreter script
46: is a file which has been set executable (see
47: .Xr chmod 2 )
48: and which has a first line of the form:
49: .Pp
50: .D1 Li #! Ar pathname Op Ar argument
51: .Pp
52: The
53: .Dq #!
54: must appear as the first two characters of the file.
55: A space between the
56: .Dq #!
57: and
58: .Ar pathname
59: is optional.
60: At most one
61: .Ar argument
62: may follow
63: .Ar pathname ,
64: and the length of the entire line is limited (see below).
65: .Pp
66: If such a file is executed (such as via the
67: .Xr execve 2
68: system call), the interpreter specified by the
69: .Ar pathname
70: is executed by the system.
71: (The
72: .Ar pathname
73: is executed without regard to the
74: .Ev PATH
75: variable, so in general
76: .Ar pathname
77: should be an absolute path.)
78: .Pp
79: The arguments passed to the interpreter will be as follows.
80: .Va argv[0]
81: will be the path to the interpreter itself, as specified on the first
82: line of the script.
83: If there is an
84: .Ar argument
85: following
86: .Ar pathname
87: on the first line of the script, it will be passed as
88: .Va argv[1] .
89: The subsequent elements of
90: .Va argv
91: will be the path to the interpreter script file itself (i.e. the
92: original
93: .Va argv[0] )
94: followed by any further arguments passed when
95: .Xr execve 2
96: was invoked to execute the script file.
97: .Pp
98: By convention, it is expected that an interpreter will open the script
99: file passed as an argument and process the commands within it.
100: Typical interpreters treat
1.2 wiz 101: .Sq #
1.1 perry 102: as a comment character, and thus will ignore the initial line of the script
103: because it begins
104: .Dq #! ,
105: but there is no requirement for this per se.
106: .Pp
107: On
108: .Nx ,
109: the length of the
110: .Dq #!
111: line, excluding the
112: .Dq #!
113: itself, is limited to
114: .Dv PATH_MAX
115: (as defined in
1.6 ! joerg 116: .In limits.h ) .
1.1 perry 117: Other operating systems impose much smaller limits on the length of
118: the
119: .Dq #!
120: line (see below).
121: .Pp
122: Note that the interpreter may not itself be an interpreter script.
123: If
124: .Ar pathname
125: does not point to an executable binary, execution of the interpreter
126: script will fail.
127: .Ss Trampolines and Portable Scripts
128: Different operating systems often have interpreters located in
129: different locations, and the kernel executes the passed interpreter
130: without regard to the setting of environment variables such as
131: .Ev PATH .
132: This makes it somewhat challenging to set the
133: .Dq #!
134: line of a script so that it will run identically on different systems.
135: .Pp
136: Since the
137: .Xr env 1
138: utility executes a command passed to it on its command line, it is
139: often used as a
140: .Dq trampoline
141: to render scripts portable.
142: If the leading line of a script reads
143: .Dl #! /usr/bin/env interp
144: then the
145: .Xr env 1
146: command will execute the
147: .Dq interp
148: command it finds in its
149: .Ev PATH ,
150: passing on to it all subsequent arguments with which it itself was called.
151: Since
152: .Pa /usr/bin/env
153: is found on almost all
154: .Tn POSIX
155: style systems, this trick is frequently exploited by authors who need
156: a script to execute without change on multiple systems.
157: .Ss Historical Note: Scripts without Dq #!
158: Shell scripts predate the invention of the
159: .Dq #!
160: convention, which is implemented in the kernel.
161: In the days of
162: .At v7 ,
163: there was only one interpreter used on the system,
164: .Pa /bin/sh ,
165: and the shell treated any file that failed to execute with an
166: .Er ENOEXEC
167: error
168: (see
169: .Xr intro 2 )
170: as a shell script.
171: .Pp
172: Most shells (such as
173: .Xr sh 1 )
174: and certain other facilities (including
175: .Xr execlp 3
176: and
177: .Xr execvp 3
178: but not other types of
179: .Xr exec 3
180: calls) still pass
181: interpreter scripts that do not include the
182: .Dq #!
183: (and thus fail to execute with
184: .Er ENOEXEC )
185: to
186: .Pa /bin/sh .
187: .Pp
188: As this behavior is implemented outside the kernel, there is no
189: mechanism that forces it to be respected by all programs that execute
190: other programs.
191: It is thus not completely reliable.
192: It is therefore important to always include
193: .Dl #!/bin/sh
194: in front of Bourne shell scripts, and to treat the traditional
195: behavior as obsolete.
196: .Sh EXAMPLES
197: Suppose that an executable binary exists in
198: .Pa /bin/interp
199: and that the file
200: .Pa /tmp/script
201: contains:
202: .Bd -literal -offset indent
203: #!/bin/interp -arg
204:
205: [...]
206: .Ed
207: .Pp
208: and that
209: .Pa /tmp/script
210: is set mode 755.
211: .Pp
212: Executing
213: .Pp
214: .Dl $ /tmp/script one two three
215: .Pp
216: at the shell will result in
217: .Pa /bin/interp
218: being executed, receiving the following arguments in
219: .Va argv
220: (numbered from 0):
221: .Pp
222: .Bd -ragged -offset indent
223: .Qq /bin/interp ,
224: .Qq "-arg" ,
225: .Qq /tmp/script ,
226: .Qq one ,
227: .Qq two ,
228: .Qq three
229: .Ed
230: .Ss Portability Note: Multiple arguments
231: The behavior of multiple arguments on the
232: .Dq #!
1.2 wiz 233: line is highly non-portable between different systems.
234: In general, only one argument can be assumed to work consistently.
1.1 perry 235: .Pp
1.2 wiz 236: Consider the following variation on the previous example.
237: Suppose that an executable binary exists in
1.1 perry 238: .Pa /bin/interp
239: and that the file
240: .Pa /tmp/script
241: contains:
242: .Bd -literal -offset indent
243: #!/bin/interp -x -y
244:
245: [...]
246: .Ed
247: .Pp
248: and that
249: .Pa /tmp/script
250: is set mode 755.
251: .Pp
252: Executing
253: .Pp
254: .Dl $ /tmp/script one two three
255: .Pp
256: at the shell will result in
257: .Pa /bin/interp
258: being executed, receiving the following arguments in
259: .Va argv
260: (numbered from 0):
261: .Pp
262: .Bd -ragged -offset indent
263: .Qq /bin/interp ,
264: .Qq "-x -y" ,
265: .Qq /tmp/script ,
266: .Qq one ,
267: .Qq two ,
268: .Qq three
269: .Ed
270: .Pp
271: Note that
272: .Qq "-x -y"
273: will be passed on
274: .Nx
275: as a single argument.
276: .Pp
277: Although most
278: .Tn POSIX
279: style operating systems will pass only one
280: .Ar argument ,
1.3 wiz 281: the behavior when multiple arguments are included is not
1.1 perry 282: consistent between platforms.
283: Some, such as current releases of
284: .Nx ,
285: will concatenate multiple arguments into a single argument (as above),
286: some will truncate them, and at least one will pass them as multiple
287: arguments.
288: .Pp
289: The
290: .Nx
291: behavior is common but not universal.
292: Sun's
293: .Tn Solaris
294: would present the above argument as
295: .Qq -x ,
296: dropping the
297: .Qq " -y"
298: entirely.
299: Perhaps uniquely, recent versions of Apple's
300: .Tn OS X
301: will actually pass multiple arguments properly, i.e.:
302: .Bd -ragged -offset indent
303: .Qq /bin/interp ,
304: .Qq -x ,
305: .Qq -y ,
306: .Qq /tmp/script ,
307: .Qq one ,
308: .Qq two ,
309: .Qq three
310: .Ed
311: .Pp
312: The behavior of the system in the face of multiple arguments is thus
313: not currently standardized, should not be relied on, and may be
314: changed in future releases.
315: In general, pass at most one argument, and do not rely on multiple
316: arguments being concatenated.
317: .Sh SEE ALSO
318: .Xr awk 1 ,
1.2 wiz 319: .Xr csh 1 ,
320: .Xr ksh 1 ,
1.1 perry 321: .Xr sh 1 ,
322: .Xr chmod 2 ,
323: .Xr execve 2 ,
324: .Xr intro 2 ,
325: .Xr execlp 3 ,
326: .Xr execvp 3 ,
327: .Xr fd 4 ,
328: .Xr options 4 ,
329: .Xr setuid 7
330: .Sh STANDARDS
331: The behavior of interpreter scripts is obliquely referred to, but
332: never actually described in,
333: .St -p1003.1-2004 .
334: .Pp
335: The behavior is partially (but not completely) described in the
336: .St -svid4 .
337: .Pp
338: Although it has never been formally standardized, the behavior
339: described is largely portable across
340: .Tn POSIX
341: style systems, with two significant exceptions: the maximum length of the
342: .Dq #!
343: line, and the behavior if multiple arguments are passed.
344: Please be aware that some operating systems limit the line to 32
345: or 64 characters, and that (as described above) the behavior in the
346: face of multiple arguments is not consistent across systems.
347: .Sh HISTORY
348: The behavior of the kernel when encountering scripts that start in
349: .Dq #!
350: was not present in
351: .At v7 .
352: A Usenet posting to net.unix by Guy Harris on October 16, 1984 claims
353: that the idea for the
354: .Dq #!
355: behavior was first proposed by Dennis Ritchie but that the first
356: implementation was on
357: .Bx .
358: .Pp
359: Historical manuals (specifically the exec man page) indicate that the
360: behavior was present in
361: .Bx 4
362: at least as early as April, 1981.
363: Information on precisely when it was first implemented, and in which
364: version of
365: .Ux ,
366: is solicited.
1.4 wiz 367: .Sh SECURITY CONSIDERATIONS
368: Numerous security problems are associated with setuid interpreter
369: scripts.
370: .Pp
371: In addition to the fact that many interpreters (and scripts) are
372: simply not designed to be robust in a setuid context, a race condition
373: exists between the moment that the kernel examines the interpreter
374: script file and the moment that the newly invoked interpreter opens
375: the file itself.
376: .Pp
377: Because of these security issues,
378: .Nx
379: does not allow setuid interpreter scripts by default.
380: In order to turn on setuid interpreter scripts,
381: .D1 Cd options SETUIDSCRIPTS
382: must be set in the configuration of the running kernel.
383: Setting this option implies the
384: .Cd FDSCRIPTS
385: option, which causes the kernel to open the script file on behalf of
386: the interpreter and pass it in
387: .Va argv
388: as
389: .Pa /dev/fd/[fdnum] .
390: (See
391: .Xr fd 4
392: for an explanation of the
393: .Pa /dev/fd/[fdnum]
394: devices.)
395: This design avoids the race condition, at the cost of denying the
396: interpreter the actual name of the script file.
397: See
398: .Xr options 4
399: for more information.
400: .Pp
401: However, the
402: .Cd FDSCRIPTS
403: mechanism is not a cure-all for security issues in setuid interpreters
404: and scripts.
405: Subtle techniques can be used to subvert even seemingly well written scripts.
406: Scripts executed by Bourne type shells can be subverted in numerous
407: ways, such as by setting the
408: .Ev IFS
409: variable before executing the script.
410: Other interpreters possess their own vulnerabilities.
411: Turning on
412: .Cd SETUIDSCRIPTS
413: is therefore very dangerous, and should not be done lightly if at all.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to script.7 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / share / man / man7