PenTest/nmap
1
0
Fork 0
mirror of https://github.com/nmap/nmap.git synced 2025-12-15 20:29:03 +00:00
Code Issues Projects Releases Wiki Activity

Many changes from David:

Browse Source 
Remove duplicate indexterms. Some of them were just too close together.
Some of
them were "see also" entries; I didn't realize that
        <indexterm><primary>a</primary></indexterm>
        <indexterm><primary>a</primary><seealso>b</seealso></indexterm>
would create two entries for "a" on that page. There were also a few
instances
where I had a <primary> definition in an <indexterm class="endofrange"> tag.

book-3.diff (include MJB-* diagrams):
Crop out the titles of packet header diagrams.

book-4.diff:
Miscellaneous index and other fixes.

book-5.diff:
Run indexterms into the same line when they appear in a paragraph. The way I
was doing it before (with indexterms on separate lines) caused an extra space
to be inserted. This was especially visible in the OS detection chapter where
there were long strings of indexterms naming response tests.

book-6.diff:
Do some more cleanup. nmap-intro said it covered export control but it
didn't,
so I removed the mention of it. I thought that -ff made smaller fragments,
but
it makes bigger fragments, so an index entry has been amended. There was a
typo
<optino>; somehow that didn't give an error.
This commit is contained in:
fyodor
2008-07-10 01:53:18 +00:00
parent 7a59fa97c5
commit 68f94e4ef4
3 changed files with 338 additions and 444 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
docs/nmap-install.xml
View File

@@ -21,8 +21,8 @@ have it. Many free operating system distributions (including most
Linux and BSD systems) come with Nmap, although it may not be
installed by default. On Unix systems, open a terminal window and try executing the command
<command>nmap <option>--version</option></command>.
If Nmap exists and is in your <envar>PATH</envar>,
<indexterm><primary><envar>PATH</envar> environment variable</primary></indexterm>
If Nmap exists and is in your
<envar>PATH</envar>,<indexterm><primary><envar>PATH</envar> environment variable</primary></indexterm>
you should see output similar to <xref linkend="ex-checking-for-nmap" />.</para>
<indexterm><primary>version number of Nmap</primary><see><option>--version</option></see></indexterm>
@@ -47,13 +47,11 @@ version number (here <literal>4.65</literal>).</para>
<para>Even if your system already has a copy of Nmap, you should
consider upgrading to the latest version available from <ulink
url="http://nmap.org/download.html" />.
<indexterm><primary>downloading</primary></indexterm>
url="http://nmap.org/download.html" />.<indexterm><primary>downloading</primary></indexterm>
Newer versions often run faster, fix important bugs, and feature
updated operating system and service version detection databases. A
list of changes since the version already on your system can be found
at <ulink url="http://nmap.org/changelog.html" />.
<indexterm><primary>changelog</primary></indexterm>
at <ulink url="http://nmap.org/changelog.html" />.<indexterm><primary>changelog</primary></indexterm>
<bookex>
Nmap output examples in this book may not match the output produced by
older versions.
@@ -134,10 +132,10 @@ forge and properly sign a trojan release. While numerous applications
are able to verify PGP signatures, I recommend the <ulink
url="http://www.gnupg.org/">GNU Privacy Guard (GPG)</ulink>.</para>
<para>
<indexterm><primary>keys, cryptographic</primary></indexterm>
Nmap releases are signed with a special Nmap Project Signing Key,
<indexterm><primary>Nmap Project Signing Key</primary></indexterm>
<para>
Nmap releases are signed with a special
Nmap Project Signing Key,<indexterm><primary>Nmap Project Signing Key</primary></indexterm>
which can be obtained from they major keyservers or <ulink
url="http://nmap.org/data/nmap_gpgkeys.txt"/>. My key is
included in that file too. The keys can be imported with the command
@@ -197,9 +195,8 @@ gpg: BAD signature from
</screen></example>
<para>While PGP signatures are the recommended validation technique,
SHA1 and MD5 (among other) hashes
<indexterm><primary>hashes, cryptographic</primary></indexterm>
<indexterm><primary>digests, cryptographic</primary></indexterm>
SHA1 and MD5 (among other)
hashes<indexterm><primary>hashes, cryptographic</primary></indexterm><indexterm><primary>digests, cryptographic</primary></indexterm>
are made available for more casual
validation. An attacker who can manipulate your Internet traffic in
real time (and is extremely skilled) or who compromises Nmap.Org
@@ -286,8 +283,9 @@ url="http://cgi.insecure.org/mailman/listinfo/nmap-svn"/>.</para>
</sect1>
<sect1 id="inst-source"><title>Unix Compilation and Installation from Source Code</title>
<indexterm><primary>Unix</primary><secondary>installing on</secondary></indexterm>
<indexterm><primary>installation</primary><secondary>from source</secondary></indexterm>
<indexterm><primary>Unix, installing on</primary></indexterm>
<indexterm><primary>Linux, compiling on</primary></indexterm>
<indexterm><primary>installation</primary><secondary>from source code</secondary></indexterm>
<indexterm><primary>source code</primary></indexterm>
<indexterm><primary>compilation</primary></indexterm>
@@ -378,7 +376,7 @@ I would run <command>./configure --prefix=<replaceable>/home/fyodor</replaceable
<listitem><indexterm><primary>Zenmap</primary><secondary>disabling</secondary></indexterm><para>This option prevents the Zenmap graphical frontend from being installed. Normally the build system checks your system for requirements such as the Python scripting language and then installs Zenmap if they are all available.</para></listitem></varlistentry>
<varlistentry><term><option>--with-openssl=</option><replaceable>directoryname</replaceable></term>
<listitem><para><indexterm><primary>OpenSSL</primary><secondary>disabling</secondary></indexterm>The version detection subsystem of Nmap is able to probe SSL-encrypted services using the free OpenSSL libraries. Normally the Nmap build system looks for these libraries on your system and include this capability if they are found. If they are in a location your compiler does not search for by default, but you still want them to be used, specify <option>--with-openssl=<replaceable>directoryname</replaceable></option>. Nmap then looks in <replaceable>directoryname</replaceable>/libs for the OpenSSL libraries themselves and <replaceable>directoryname</replaceable>/include for the necessary header files. Specify <option>--without-openssl</option> to disable SSL entirely.</para></listitem></varlistentry>
<listitem><indexterm><primary>OpenSSL</primary><secondary>disabling</secondary></indexterm><para>The version detection subsystem of Nmap is able to probe SSL-encrypted services using the free OpenSSL libraries. Normally the Nmap build system looks for these libraries on your system and include this capability if they are found. If they are in a location your compiler does not search for by default, but you still want them to be used, specify <option>--with-openssl=<replaceable>directoryname</replaceable></option>. Nmap then looks in <replaceable>directoryname</replaceable>/libs for the OpenSSL libraries themselves and <replaceable>directoryname</replaceable>/include for the necessary header files. Specify <option>--without-openssl</option> to disable SSL entirely.</para></listitem></varlistentry>
<varlistentry><term><option>--with-libpcap=</option><replaceable>directoryname</replaceable></term>
<listitem><para>Nmap uses the <ulink url="http://www.tcpdump.org">Libpcap library</ulink> for capturing raw IP packets. Nmap normally looks for an existing copy of Libpcap on your system and uses that if the version number and platform is appropriate. Otherwise Nmap includes its own recent copy of Libpcap, which has been modified for improved Linux functionality. The specific changes are described in <filename>libpcap/NMAP_MODIFICATIONS</filename> in the Nmap source directory. Because of these Linux-related changes, Nmap always uses its own Libpcap by default on that platform. If you wish to force Nmap to link with your own Libpcap, pass the option <option>--with-libpcap=<replaceable>directoryname</replaceable></option> to <application>configure</application>. Nmap then expects the Libpcap library to be in <filename><replaceable>directoryname</replaceable>/lib/libpcap.a</filename> and the include files to be in <filename><replaceable>directoryname</replaceable>/include</filename>. Nmap will always use the version of Libpcap included in its tarball if you specify <option>--with-libpcap=included</option>.
@@ -415,14 +413,13 @@ If you make code changes to fix the problem, please send a patch
(created with <command>diff -uw oldfile newfile</command>) and any details about your problem and platform to me at <email>fyodor@insecure.org</email>. Integrating the change into the base Nmap distribution allows many other users to benefit, and prevents you from having to make the changes with each new Nmap version.</para></listitem></varlistentry>
<varlistentry><term>Ask Google and other Internet resources</term>
<listitem><para>Try searching for the exact error message on Google or other search engines. You might also want to browse recent activity on the Nmap development (<citetitle>nmap-dev</citetitle>)
<indexterm><primary><citetitle>nmap-dev</citetitle> mailing list</primary></indexterm>
<listitem><para>Try searching for the exact error message on Google or other search engines. You might also want to browse recent activity on the Nmap development
(<citetitle>nmap-dev</citetitle>)<indexterm><primary><citetitle>nmap-dev</citetitle> mailing list</primary></indexterm>
list&mdash;archives are available at <ulink url="http://seclists.org" />.</para></listitem></varlistentry>
<varlistentry><term>Ask <citetitle>nmap-dev</citetitle></term>
<listitem><para>If none of your research has led to a solution for
your problem, try sending a report to the Nmap development (<citetitle>nmap-dev</citetitle>)
<indexterm><primary><citetitle>nmap-dev</citetitle> mailing list</primary></indexterm>
list. If you subscribe first, your message gets through faster
because it does not go through moderation. Subscribe by
sending a blank email to
@@ -448,10 +445,8 @@ packages.</para></listitem></varlistentry>
</sect1>
<sect1 id="inst-linux"><title>Linux Distributions</title>
<indexterm><primary>Linux</primary><secondary>installing on</secondary></indexterm>
<para>
<indexterm><primary>Linux</primary><secondary>popularity as Nmap platform</secondary></indexterm>
Linux is far and away the most popular platform for running
Nmap. In one user survey, 86% said that Linux was at
least one of the platforms on which they run
@@ -474,6 +469,7 @@ the most common distributions.</para>
<sect2 id="inst-rpm"><title>RPM-based Distributions (Red Hat, Mandrake, Suse, Fedora)</title>
<indexterm><primary>RPM</primary></indexterm>
<indexterm><primary>Linux</primary><secondary>installing on, with RPM</secondary>></indexterm>
<indexterm><primary>Red Hat (Linux distribtion)</primary><secondary>installing on, with RPM</secondary>></indexterm>
<indexterm><primary>Mandrake (Linux distribution)</primary><secondary>installing on, with RPM</secondary></indexterm>
<indexterm><primary>Suse (Linux distribution)</primary><secondary>installing on, with RPM</secondary></indexterm>
@@ -536,6 +532,7 @@ reason there are no Zenmap source RPMs.</para>
<sect2 id="inst-yum"><title>Updating Red Hat, Fedora, Mandrake, and Yellow Dog Linux with Yum</title>
<indexterm><primary>Yum</primary></indexterm>
<indexterm><primary>Linux</primary><secondary>installing on, with Yum</secondary></indexterm>
<indexterm><primary>Red Hat (Linux distribtion)</primary><secondary>installing on, with Yum</secondary></indexterm>
<indexterm><primary>Mandrake (Linux distribution)</primary><secondary>installing on, with Yum</secondary></indexterm>
<indexterm><primary>Yellow Dog (Linux distribution)</primary><secondary>installing on, with Yum</secondary></indexterm>
@@ -609,8 +606,9 @@ Complete!
</sect2>
<sect2 id="inst-debian"><title>Debian Linux and Derivatives such as Ubuntu</title>
<indexterm><primary>Debian</primary><secondary>installing on</secondary></indexterm>
<indexterm><primary>Ubuntu</primary><secondary>installing on</secondary></indexterm>
<indexterm><primary>Linux</primary><secondary>installing on, with <application>apt-get</application></secondary></indexterm>
<indexterm><primary>Debian, installing on</primary></indexterm>
<indexterm><primary>Ubuntu, installing on</primary></indexterm>
<para>LaMont Jones
<indexterm><primary>Jones, LaMont</primary></indexterm>
does a fabulous job maintaining the Nmap .deb
@@ -635,14 +633,12 @@ described in <xref linkend="inst-source" />.
</sect1>
<sect1 id="inst-windows"><title>Windows</title>
<indexterm><primary>Windows</primary></indexterm>
<indexterm class="startofrange" id="inst-windows-indexterm"><primary>Windows</primary></indexterm>
<indexterm><primary>Microsoft Windows</primary><see>Windows</see></indexterm>
<para>While Nmap was once a Unix-only tool, a Windows version was
released in 2000 and has since become the second most popular Nmap
platform (behind Linux).
<indexterm><primary>Windows</primary><secondary>popularity as Nmap platform</secondary></indexterm>
Because of this popularity and the fact that
platform (behind Linux). Because of this popularity and the fact that
many Windows users do not have a compiler, binary executables are
distributed for each major Nmap release. While it has improved
dramatically, the Windows port is not quite as efficient or stable as
@@ -693,8 +689,6 @@ the <literal>CurrentControlSet\Services\Tcpip\Parameters</literal> entry under <
years, Nmap was a Unix-only tool, and it would likely still be that
way if not for their efforts.</para></note>
<indexterm><primary>Windows</primary><secondary>installing on</secondary></indexterm>
<para>Windows users have three choices for installing
Nmap, all of which are available from the
download page at <ulink url="http://nmap.org/download.html" />.</para>
@@ -702,7 +696,7 @@ download page at <ulink url="http://nmap.org/download.html" />.</para>
<sect2 id="inst-win-exe"><title>Windows Self-installer</title>
<indexterm><primary>Windows</primary><seconary>self-installer</seconary></indexterm>
<indexterm><primary>Windows</primary><secondary>self-installer</secondary></indexterm>
<para>Every major &ldquo;stable&rdquo; Nmap release comes with Windows
self-installer named
@@ -720,7 +714,7 @@ command-line.</para>
</sect2>
<sect2 id="inst-win-zip"><title>Command-line Zip Binaries</title>
<indexterm><primary>Windows</primary><seconary>zip binaries</seconary></indexterm>
<indexterm><primary>Windows</primary><secondary>zip binaries</secondary></indexterm>
<note><para>Most users prefer installing Nmap with the self-installer discussed previously.</para></note>
@@ -729,8 +723,8 @@ command-line binaries and associated files in a Zip archive. No
graphical interface is included, so you need to run
<literal>nmap.exe</literal> from a DOS/command window. Or you can
download and install a superior command shell such as those included
with the free Cygwin
<indexterm><primary>Cygwin</primary></indexterm>
with the free
Cygwin<indexterm><primary>Cygwin</primary></indexterm>
system available from <ulink url="http://www.cygwin.com" />. Here are the step-by-step instructions for installing and executing the Nmap .zip binaries.</para>
<sect3 id="inst-win-zip-install"><title>Installing the Nmap zip binaries</title>
@@ -769,7 +763,7 @@ WinPcap requirement.</para></listitem>
</sect2>
<sect2 id="inst-win-source"><title>Compile from Source Code</title>
<indexterm><primary>Windows</primary><secondary>compilation on</secondary></indexterm>
<indexterm><primary>Windows</primary><secondary>compiling on</secondary></indexterm>
<para>Most Windows users prefer to use the Nmap binary self-installer,
@@ -804,6 +798,7 @@ Cygwin.</para>
</sect2>
<sect2 id="inst-win-exec"><title>Executing Nmap on Windows</title>
<indexterm><primary>Windows</primary><secondary>running Nmap on</secondary></indexterm>
<para>Nmap releases now include the
<application>Zenmap</application> graphical user interface for Nmap. If
@@ -815,8 +810,8 @@ detailed instructions for users who are unfamiliar with command-line
interfaces:</para>
<orderedlist>
<listitem><para>Make sure the user you are logged in as has administrative privileges
<indexterm><primary>privileged users</primary></indexterm>
<listitem><para>Make sure the user you are logged in as has
administrative privileges<indexterm><primary>privileged users</primary></indexterm>
on the computer (user should be a member of the <literal>administrators</literal> group).</para></listitem>
<listitem><para>Open a command/DOS Window. Though it can be found in
the program menu tree, the simplest approach is to choose <guimenu>Start</guimenu>
@@ -859,8 +854,9 @@ Computer</literal> and then click <guimenuitem>properties</guimenuitem>.</para><
<listitem><para>Click the <guimenuitem>Environment
Variables</guimenuitem> button.</para></listitem>
<listitem><para>
<listitem>
<indexterm><primary><envar>PATH</envar> environment variable</primary><secondary><envar>Path</envar> on Windows</secondary></indexterm>
<para>
Choose <literal>Path</literal> from the
<literal>System variables</literal> section, then hit
edit.</para></listitem>
@@ -874,16 +870,17 @@ command such as <command>nmap scanme.nmap.org</command> from any directory.</par
</sect2>
<indexterm class="endofrange" startref="inst-windows-indexterm"/>
</sect1>
<sect1 id="inst-solaris"><title>Sun Solaris</title>
<indexterm><primary>Solaris</primary></indexterm>
<indexterm><primary>Solaris, installing on</primary></indexterm>
<indexterm><primary>Sun Solaris</primary><see>Solaris</see></indexterm>
<para>Solaris has long been well-supported by Nmap. Sun even donated a complete SPARCstation to the project, which is still being used to test new Nmap builds. For this reason, many Solaris users compile and install from source code as described in <xref linkend="inst-source" />.</para>
<para>Users who prefer native Solaris packages will be pleased to
learn that Steven Christensen
<indexterm><primary>Christensen, Steven</primary></indexterm>
learn that
Steven Christensen<indexterm><primary>Christensen, Steven</primary></indexterm>
does an excellent job of maintaining
Nmap packages over at <ulink url="http://www.sunfreeware.com" />. Instructions are
on his site, and are generally very simple: download the
@@ -898,7 +895,7 @@ you have more flexibility in the build process.
</sect1>
<sect1 id="inst-macosx"><title>Apple Mac OS X</title>
<indexterm><primary>Mac OS X</primary><secondary>installing on</secondary></indexterm>
<indexterm class="startofrange" id="inst-macosx-indexterm"><primary>Mac OS X</primary></indexterm>
<indexterm><primary>Apple Mac OS X</primary><see>Mac OS X</see></indexterm>
<para>Thanks to several people graciously donating shell accounts on
@@ -918,9 +915,8 @@ the installer. In the
the Nmap download page</ulink> there is a file called
<filename>nmap-<replaceable>version</replaceable>.dmg</filename>, where
<replaceable>version</replaceable> is the version number of the most
recent release. The <filename>.dmg</filename>
<indexterm><primary sortas="dmg"><filename>.dmg</filename> (Mac OS X disk image)</primary></indexterm>
<indexterm><primary>disk image (Mac OS X)</primary></indexterm>
recent release. The
<filename>.dmg</filename><indexterm><primary sortas="dmg"><filename>.dmg</filename> (Mac OS X disk image)</primary></indexterm><indexterm><primary>disk image (Mac OS X)</primary></indexterm>
file is known as a
<quote>disk image</quote>. This is the process for installing from the
disk image.</para>
@@ -951,7 +947,7 @@ have to compile from source or use a third-party package.</para>
</sect2>
<sect2 id="inst-macosx-source">
<indexterm><primary>Mac OS X</primary><secondary>compilation on</secondary></indexterm>
<indexterm><primary>Mac OS X</primary><secondary>compiling on</secondary></indexterm>
<title>Compile from Source Code</title>
<para>Compiling Nmap from source on Mac OS X is no more difficult than
@@ -961,8 +957,7 @@ on other platforms once a proper build environment is in place.</para>
<title>Compile Nmap from source code</title>
<para>Compiling Nmap on Mac OS X requires
<ulink url="http://developer.apple.com/tools/xcode/">Xcode</ulink>,
<indexterm><primary>Xcode</primary></indexterm>
<ulink url="http://developer.apple.com/tools/xcode/">Xcode</ulink>,<indexterm><primary>Xcode</primary></indexterm>
Apple's developer tools that include GCC and the rest of the usual build
system. Xcode is not installed by default but it is available as an
optional install on the Mac OS X installation discs. If you do not have
@@ -971,8 +966,7 @@ Xcode free of charge by following these steps.</para>
<orderedlist>
<listitem><para>Apple restricts downloads of Xcode to members of the
Apple Developer Connection.
<indexterm><primary>Apple Developer Connection</primary></indexterm>
Apple Developer Connection.<indexterm><primary>Apple Developer Connection</primary></indexterm>
Browse to
<ulink url="http://connect.apple.com" /> and fill out some forms to
create an account. Skip to the next step if you already have an
@@ -1006,6 +1000,7 @@ install Zenmap as usual.</para>
</sect2>
<sect2 id="inst-macosx-third-party">
<indexterm><primary>Mac OS X</primary><secondary>installing from third-party packages</secondary></indexterm>
<title>Third-party Packages</title>
<para>A further option for installing Nmap is to use one of the systems
@@ -1028,6 +1023,7 @@ install nmap</command>. Nmap will be installed as
</sect2>
<sect2 id="inst-macosx-exec">
<indexterm><primary>Mac OS X</primary><secondary>running Nmap on</secondary></indexterm>
<title>Executing Nmap on Mac OS X</title>
<para>The terminal emulator in Mac OS X is called
@@ -1035,10 +1031,10 @@ install nmap</command>. Nmap will be installed as
<filename>/Applications/Utilities</filename>. Open it and you will see a
terminal window. This is where you will type your commands.</para>
<para><indexterm><primary><command>sudo</command></primary></indexterm>
<para>
By default the root user is disabled on Mac OS X. To run a scan with
root privileges prefix the command name with <application>sudo</application>,
<indexterm><primary><application>sudo</application></primary></indexterm>
root privileges prefix the command name with
<application>sudo</application>,<indexterm><primary><application>sudo</application></primary></indexterm>
as
in <command>sudo nmap -sS <replaceable>target</replaceable></command>.
You will be asked for a password, which is just your normal login
@@ -1049,14 +1045,15 @@ be installed. If it was not installed by default it may be available as
an optional install on the Mac OS X installation discs.</para>
<para>When Zenmap is started, a dialog is displayed requesting that you
type your password. Users with administrator privileges
<indexterm><primary>privileged users</primary></indexterm>
type your password. Users with
administrator privileges<indexterm><primary>privileged users</primary></indexterm>
may enter their
password to allow Zenmap to run as the root user and run more advanced
scans. To run Zenmap in unprivileged mode, just select the
<guibutton>Cancel</guibutton> button on this dialog.</para>
</sect2>
<indexterm class="endofrange" startref="inst-macosx-indexterm"/>
</sect1>
<sect1 id="inst-bsd"><title>FreeBSD / OpenBSD / NetBSD</title>
@@ -1073,6 +1070,7 @@ popular applications. Instructions for installing Nmap on
the most popular *BSD variants follow.</para>
<sect2 id="inst-openbsd"><title>OpenBSD Binary Packages and Source Ports Instructions</title>
<indexterm><primary>OpenBSD, installing on</primary></indexterm>
<para>According to the <ulink
url="http://www.openbsd.org/faq/">OpenBSD FAQ</ulink>, users
@@ -1098,7 +1096,7 @@ Or obtain it from the OpenBSD distribution CD-ROM.</para></listitem>
</sect2>
<sect2 id="inst-freebsd"><title>FreeBSD Binary Package and Source Ports Instructions</title>
<indexterm><primary>FreeBSD</primary></indexterm>
<indexterm><primary>FreeBSD, installing on</primary></indexterm>
<para>The FreeBSD project has a whole <ulink
url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports.html">chapter</ulink>
@@ -1132,23 +1130,23 @@ chapter referenced above.</para></listitem>
</sect2>
<sect2 id="inst-netbsd"><title>NetBSD Binary Package Instructions</title>
<indexterm><primary>NetBSD</primary></indexterm>
<indexterm><primary>NetBSD, installing on</primary></indexterm>
<para>NetBSD has packaged Nmap for an enormous number of platforms, from the normal i386 to Playstation 2, PowerPC, VAX, SPARC, MIPS, Amiga, ARM, and several platforms that I have never even heard of! Unfortunately they are not very up-to-date. A list of NetBSD Nmap packages is available from <ulink url="ftp://ftp.netbsd.org/pub/NetBSD/packages/pkgsrc/net/nmap/README.html" /> and a description of using their package system to install applications is available at <ulink url="http://www.netbsd.org/Documentation/pkgsrc/using.html#id2956484" />.</para>
</sect2>
</sect1>
<sect1 id="inst-other-platforms"><title>Amiga, HP-UX, IRIX, and Other Platforms</title>
<indexterm><primary>AmigaOS</primary></indexterm>
<indexterm><primary>HP-UX</primary></indexterm>
<indexterm><primary>IRIX</primary></indexterm>
<indexterm><primary>AmigaOS, installing on</primary></indexterm>
<indexterm><primary>HP-UX, installing on</primary></indexterm>
<indexterm><primary>IRIX, installing on</primary></indexterm>
<para>One of the wonders of Open Source development is that resources
are often biased towards what people find exciting rather than having
an exclusive focus on profits as most corporations do. It is along
those lines that the Amiga port came about. Diego Casorran
<indexterm><primary>Casorran, Diego</primary></indexterm>performed
those lines that the Amiga port came about.
Diego Casorran<indexterm><primary>Casorran, Diego</primary></indexterm>performed
most of the work and sent in a clean patch which was integrated into
the main Nmap distribution. In general, AmigaOS users should be able
to simply follow the source compilation instructions in <xref
@@ -1160,8 +1158,7 @@ fanatics.</para>
SGI IRIX. The Nmap project mostly depends on the user community to
maintain adequate support for these systems. If you have trouble, try
sending a report with full details to the <citetitle>nmap-dev</citetitle> mailing list
(<email>nmap-dev@insecure.org</email>).
<indexterm><primary><citetitle>nmap-dev</citetitle> mailing list</primary></indexterm>
(<email>nmap-dev@insecure.org</email>).<indexterm><primary><citetitle>nmap-dev</citetitle> mailing list</primary></indexterm>
If you develop a patch which
improves support on your platform, please email it to <citetitle>nmap-dev</citetitle> or to me at <email>fyodor@insecure.org</email>.</para>
</sect1>
@@ -1182,8 +1179,7 @@ megabytes of disk space it consumes.</para>
<para>How to remove Nmap depends on how
you installed it initially (see previous sections). Ease of removal (and other maintenance) is a major advantage of most binary packages. For example, when Nmap is installed using
the RPM
<indexterm><primary>RPM</primary></indexterm>
the RPM<indexterm><primary>RPM</primary></indexterm>
system common on Linux distributions, it can be removed by
running the command <command>rpm -e nmap
zenmap</command> as root. Analogous options are offered by

424
docs/refguide.xml
View File

@@ -51,30 +51,30 @@
<para>The output from Nmap is a list of scanned targets, with
supplemental information on each depending on the options
used. Key among that information is the <quote>interesting ports
table</quote>.
<indexterm><primary>ports</primary><secondary><quote>interesting</quote></secondary></indexterm>
table</quote>.<indexterm><primary>ports</primary><secondary><quote>interesting</quote></secondary></indexterm>
That table lists the port number and protocol,
service name, and state. The state is either
<literal>open</literal>, <literal>filtered</literal>,
<literal>closed</literal>, or <literal>unfiltered</literal>.
<indexterm><primary><literal>open</literal> port state</primary></indexterm>
<literal>Open</literal> means that an application on the target machine is listening for
<literal>Open</literal><indexterm><primary><literal>open</literal> port state</primary></indexterm>
means that an application on the target machine is listening for
connections/packets on that port.
<indexterm><primary><literal>filtered</literal> port state</primary></indexterm>
<literal>Filtered</literal> means that a firewall, filter, or other network
<literal>Filtered</literal><indexterm><primary><literal>filtered</literal> port state</primary></indexterm>
means that a firewall, filter, or other network
obstacle is blocking the port so that Nmap cannot tell whether it is
<literal>open</literal> or <literal>closed</literal>.
<indexterm><primary><literal>closed</literal> port state</primary></indexterm>
<literal>Closed</literal> ports have no application listening on them,
<literal>Closed</literal><indexterm><primary><literal>closed</literal> port state</primary></indexterm>
ports have no application listening on them,
though they could open up at any time.
<indexterm><primary><literal>unfiltered</literal> port state</primary></indexterm>
Ports are classified as <literal>unfiltered</literal> when they are
Ports are classified as
<literal>unfiltered</literal><indexterm><primary><literal>unfiltered</literal> port state</primary></indexterm>
when they are
responsive to Nmap's probes, but Nmap cannot determine whether they are
open or closed.
<indexterm><primary><literal>open|filtered</literal> port state</primary></indexterm>
<indexterm><primary><literal>closed|filtered</literal> port state</primary></indexterm>
Nmap reports the state combinations <literal>open|filtered</literal> and
<literal>closed|filtered</literal> when it cannot determine which
Nmap reports the state combinations
<literal>open|filtered</literal><indexterm><primary><literal>open|filtered</literal> port state</primary></indexterm>
and <literal>closed|filtered</literal><indexterm><primary><literal>closed|filtered</literal> port state</primary></indexterm>
when it cannot determine which
of the two states describe a port. The port table may also
include software version details when version detection has been
requested. When an IP protocol scan is requested
@@ -170,8 +170,8 @@ option argument) is treated as a target host specification. The
simplest case is to specify a target IP address or hostname for scanning.</para>
<para>Sometimes you wish to scan a whole network of adjacent hosts.
For this, Nmap supports CIDR-style addressing.
<indexterm><primary>CIDR (Classless Inter-Domain Routing)</primary></indexterm>
For this, Nmap supports
CIDR-style addressing.<indexterm><primary>CIDR (Classless Inter-Domain Routing)</primary></indexterm>
You can append
/<replaceable>numbits</replaceable> to an IP address or hostname and
Nmap will scan every IP address for which the first
@@ -342,8 +342,7 @@ you would expect.</para>
used for any targets which are on a local ethernet network.
For unprivileged Unix shell users, a SYN packet is sent
instead of the ACK using the <function>connect()</function>
system call.
<indexterm><primary>unprivileged users</primary><secondary>limitations of</secondary></indexterm>
system call.<indexterm><primary>unprivileged users</primary><secondary>limitations of</secondary></indexterm>
These defaults are equivalent to the
<option>-PA -PE</option> options. This host discovery is
often sufficient when scanning local networks, but a more
@@ -354,8 +353,8 @@ you would expect.</para>
ping types) can be combined. You can increase your odds of
penetrating strict firewalls by sending many probe types using
different TCP ports/flags and ICMP codes. Also note that ARP
discovery (<option>-PR</option>)
<indexterm><primary><option>-PR</option></primary></indexterm>
discovery
(<option>-PR</option>)<indexterm><primary><option>-PR</option></primary></indexterm>
is done by default against
targets on a local ethernet network even if you specify other
<option>-P*</option> options, because it is almost always faster
@@ -435,8 +434,7 @@ you would expect.</para>
(using a <function>connect()</function> call) to port 80 on
the target. When a privileged user tries to scan targets
on a local ethernet network, ARP requests
(<option>-PR</option>)
<indexterm><primary><option>-PR</option></primary></indexterm>
(<option>-PR</option>)<indexterm><primary><option>-PR</option></primary></indexterm>
are used unless
<option>--send-ip</option> was specified.
The <option>-sP</option> option can be combined with any of the
@@ -509,8 +507,8 @@ you would expect.</para>
are attempting to establish a connection. Normally the
destination port will be closed, and a RST (reset) packet
sent back. If the port happens to be open, the target will
take the second step of a TCP 3-way-handshake
<indexterm><primary>three-way handshake</primary></indexterm>
take the second step of a TCP
3-way-handshake<indexterm><primary>three-way handshake</primary></indexterm>
by responding
with a SYN/ACK TCP packet. The machine running Nmap then
tears down the nascent connection by responding with a RST
@@ -525,16 +523,13 @@ you would expect.</para>
Nmap that the host is available and responsive.</para>
<para>On Unix boxes, only the privileged user
<literal>root</literal>
<indexterm><primary>privileged users</primary></indexterm>
is generally able to send and
receive raw TCP packets.
<indexterm><primary>raw packets</primary></indexterm>
<literal>root</literal><indexterm><primary>privileged users</primary></indexterm>
is generally able to send and receive
raw TCP packets.<indexterm><primary>raw packets</primary></indexterm>
For unprivileged users, a
workaround is automatically employed whereby the connect()
system call is initiated against each target port.
<indexterm><primary>unprivileged users</primary><secondary>limitations of</secondary></indexterm>
This has
workaround is automatically employed<indexterm><primary>unprivileged users</primary><secondary>limitations of</secondary></indexterm>
whereby the connect() system call is initiated against each
target port. This has
the effect of sending a SYN packet to the target host, in an
attempt to establish a connection. If connect() returns
with a quick success or an ECONNREFUSED failure, the
@@ -543,8 +538,7 @@ you would expect.</para>
is left hanging until a timeout is reached, the host is
marked as down. This workaround is also used for IPv6
connections, as raw IPv6 packet building support is not yet
available in Nmap.
<indexterm><primary>IPv6</primary><secondary>limitations of</secondary></indexterm>
available in Nmap.<indexterm><primary>IPv6</primary><secondary>limitations of</secondary></indexterm>
</para>
</listitem>
@@ -584,8 +578,7 @@ you would expect.</para>
outgoing connections to the Internet. This non-stateful
approach takes up few resources on the firewall/router and
is widely supported by hardware and software filters. The
Linux Netfilter/iptables
<indexterm><primary>iptables</primary></indexterm>
Linux Netfilter/iptables<indexterm><primary>iptables</primary></indexterm>
firewall software offers the
<option>--syn</option> convenience option to implement this
stateless approach. When stateless firewall rules such as
@@ -623,10 +616,8 @@ you would expect.</para>
<option>-PS</option> and <option>-PA</option> options. If
no ports are specified, the default is 31338. This default
can be configured at compile-time by changing
<varname>DEFAULT_UDP_PROBE_PORT_SPEC</varname>
<indexterm><primary><varname>DEFAULT_UDP_PROBE_PORT_SPEC</varname></primary></indexterm>
in <filename>nmap.h</filename>.
<indexterm><primary><filename>nmap.h</filename></primary></indexterm>
<varname>DEFAULT_UDP_PROBE_PORT_SPEC</varname><indexterm><primary><varname>DEFAULT_UDP_PROBE_PORT_SPEC</varname></primary></indexterm>
in <filename>nmap.h</filename>.<indexterm><primary><filename>nmap.h</filename></primary></indexterm>
A highly uncommon port is used by default because sending to
open ports is often undesirable for this particular scan
type.</para>
@@ -672,8 +663,7 @@ you would expect.</para>
<application>ping</application> program. Nmap sends an ICMP
type 8 (echo request) packet to the target IP addresses,
expecting a type 0 (echo reply) in return from available
hosts.
<indexterm><primary>ICMP echo</primary></indexterm>
hosts.<indexterm><primary>ICMP echo</primary></indexterm>
Unfortunately for network explorers, many hosts and
firewalls now block these packets, rather than responding as
required by <ulink
@@ -725,10 +715,8 @@ you would expect.</para>
IP packets for ICMP (protocol 1), IGMP (protocol 2), and
IP-in-IP (protocol 4). The default protocols can be
configured at compile-time by changing
<varname>DEFAULT_PROTO_PROBE_PORT_SPEC</varname>
<indexterm><primary><varname>DEFAULT_PROTO_PROBE_PORT_SPEC</varname></primary></indexterm>
in <filename>nmap.h</filename>.
<indexterm><primary><filename>nmap.h</filename></primary></indexterm>
<varname>DEFAULT_PROTO_PROBE_PORT_SPEC</varname><indexterm><primary><varname>DEFAULT_PROTO_PROBE_PORT_SPEC</varname></primary></indexterm>
in <filename>nmap.h</filename>.<indexterm><primary><filename>nmap.h</filename></primary></indexterm>
Note that for the ICMP, IGMP, TCP (protocol 6), and UDP
(protocol 17), the packets are sent with the proper protocol
headers while other protocols are sent with no additional data
@@ -814,8 +802,8 @@ Nmap can provide is determined by the type of scan or ping. The SYN
scan and SYN ping (<option>-sS</option> and <option>-PS</option>) are very detailed, but the
TCP connect scan (<option>-sT</option>) is limited by the
implementation of the <literal>connect</literal> system call. This feature is automatically enabled by
the debug option (<option>-d</option>)
<indexterm><primary><option>--reason</option></primary><secondary>implied by <option>-d</option></secondary></indexterm>
the debug option
(<option>-d</option>)<indexterm><primary><option>--reason</option></primary><secondary>implied by <option>-d</option></secondary></indexterm>
and the results are stored in XML log files
even if this option is not specified.
@@ -1018,8 +1006,8 @@ jalopy to a real mechanic, he invariably fishes around in a huge tool chest unti
pulling out the perfect gizmo which makes the job seem effortless. The
art of port scanning is similar. Experts understand the dozens of
scan techniques and choose the appropriate one (or combination) for a
given task. Inexperienced users and script kiddies,
<indexterm><primary>script kiddies</primary></indexterm>
given task. Inexperienced users and
script kiddies,<indexterm><primary>script kiddies</primary></indexterm>
on the other
hand, try to solve every problem with the default SYN scan. Since Nmap is
free, the only barrier to port scanning mastery is knowledge. That
@@ -1027,10 +1015,10 @@ certainly beats the automotive world, where it may take great skill to
determine that you need a strut spring compressor, then you still
have to pay thousands of dollars for it.</para>
<para>Most of the scan types are only available to privileged users.
<indexterm><primary>privileged users</primary></indexterm>
This is because they send and receive raw packets,
<indexterm><primary>raw packets</primary></indexterm>
<para>Most of the scan types are only available to
privileged users.<indexterm><primary>privileged users</primary></indexterm>
This is because they send and receive
raw packets,<indexterm><primary>raw packets</primary></indexterm>
which requires root
access on Unix systems. Using an administrator account on Windows is
recommended, though Nmap sometimes works for unprivileged users on that
@@ -1180,8 +1168,8 @@ out and then conduct retransmissions just in case the probe or
response were lost. Closed ports are often an even bigger problem.
They usually send back an ICMP port unreachable error. But unlike the
RST packets sent by closed TCP ports in response to a SYN or connect
scan, many hosts rate limit ICMP port unreachable messages by default.
<indexterm><primary>rate limiting</primary></indexterm>
scan, many hosts rate limit<indexterm><primary>rate limiting</primary></indexterm>
ICMP port unreachable messages by default.
Linux and Solaris are particularly strict about this. For example, the
Linux 2.4.20 kernel limits destination unreachable messages to one per
second (in <filename>net/ipv4/icmp.c</filename>).</para>
@@ -1335,10 +1323,10 @@ ports, then those three may very well be the truly open ones.</para>
</term>
<listitem>
<para>The Maimon scan is named after its discoverer, Uriel Maimon.
<indexterm><primary>Maimon, Uriel</primary></indexterm>
He described the technique in <citetitle>Phrack</citetitle> Magazine issue #49 (November 1996).
<indexterm><primary><citetitle>Phrack</citetitle></primary></indexterm>
<para>The Maimon scan is named after its discoverer,
Uriel Maimon.<indexterm><primary>Maimon, Uriel</primary></indexterm>
He described the technique in
<citetitle>Phrack</citetitle> Magazine issue #49 (November 1996).<indexterm><primary><citetitle>Phrack</citetitle></primary></indexterm>
Nmap, which included this technique, was released two issues later.
This technique is exactly the same as NULL, FIN, and Xmas scans, except
that the probe is FIN/ACK. According to <ulink role="hidepdf" url="http://www.rfc-editor.org/rfc/rfc793.txt">RFC 793</ulink> (TCP), a RST packet
@@ -1358,10 +1346,10 @@ simply drop the packet if the port is open.</para>
<para>Truly advanced Nmap users need not limit themselves to the
canned scan types offered. The <option>--scanflags</option> option allows
you to design your own scan by specifying arbitrary TCP flags.
<indexterm><primary>TCP flags</primary></indexterm>
Let your creative juices flow, while evading intrusion detection systems
<indexterm><primary>intrusion detection systems</primary><secondary>evading</secondary></indexterm>
you to design your own scan by specifying arbitrary
TCP flags.<indexterm><primary>TCP flags</primary></indexterm>
Let your creative juices flow, while evading
intrusion detection systems<indexterm><primary>intrusion detection systems</primary><secondary>evading</secondary></indexterm>
whose vendors simply paged through the Nmap man page adding specific rules!</para>
<para>The <option>--scanflags</option> argument can be a numerical
@@ -1422,9 +1410,9 @@ used.</para>
listing shows open ports
<emphasis>from the perspective of the zombie
host.</emphasis> So you can try scanning a target using
various zombies that you think might be trusted (via
router/packet filter rules).
<indexterm><primary>trust relationships</primary></indexterm>
various zombies that you think might be
trusted<indexterm><primary>trust relationships</primary></indexterm>
(via router/packet filter rules).
</para>
<para>You can add a colon followed by a port number to the
@@ -1455,12 +1443,11 @@ close enough to a port scan that it belongs here.</para>
<para>Besides being useful in its own right, protocol scan
demonstrates the power of open-source software. While the fundamental
idea is pretty simple, I had not thought to add it nor received any
requests for such functionality. Then in the summer of 2000, Gerhard
Rieger
<indexterm><primary>Rieger, Gerhard</primary></indexterm>
requests for such functionality. Then in the summer of 2000,
Gerhard Rieger<indexterm><primary>Rieger, Gerhard</primary></indexterm>
conceived the idea, wrote an excellent patch implementing it,
and sent it to the <citetitle>nmap-hackers</citetitle> mailing list.
<indexterm><primary><citetitle>nmap-hackers</citetitle> mailing list</primary></indexterm>
and sent it to the
<citetitle>nmap-hackers</citetitle> mailing list.<indexterm><primary><citetitle>nmap-hackers</citetitle> mailing list</primary></indexterm>
I incorporated that patch into the Nmap tree and released a new
version the next day. Few pieces of commercial software have users
enthusiastic enough to design and contribute their own
@@ -1566,8 +1553,8 @@ way.</para>
beginning and/or end values of a range may be omitted,
causing Nmap to use 1 and 65535, respectively. So you can
specify <option>-p-</option> to scan ports from 1 through
65535. Scanning port zero
<indexterm><primary>port zero</primary></indexterm>
65535. Scanning
port zero<indexterm><primary>port zero</primary></indexterm>
is allowed if you specify it
explicitly. For IP protocol scanning (<option>-sO</option>), this option
specifies the protocol numbers you wish to scan for
@@ -1616,9 +1603,9 @@ way.</para>
(about 1650 ports) isn't dramatic. The difference can be
enormous if you specify your own tiny
<filename>nmap-services</filename> file using the
<option>--servicedb</option> or <option>--datadir</option> options.
<indexterm><primary><option>--servicedb</option></primary></indexterm>
<indexterm><primary><option>--datadir</option></primary></indexterm>
<option>--servicedb</option><indexterm><primary><option>--servicedb</option></primary></indexterm>
or <option>--datadir</option><indexterm><primary><option>--datadir</option></primary></indexterm>
options.
</para>
</listitem>
</varlistentry>
@@ -1650,17 +1637,16 @@ way.</para>
<para>Point Nmap at a remote machine and it might tell you
that ports 25/tcp, 80/tcp, and 53/udp are open. Using its
<filename>nmap-services</filename>
<indexterm><primary><filename>nmap-services</filename></primary></indexterm>
database of about 2,200 well-known services,
<indexterm><primary>well-known ports</primary></indexterm>
<filename>nmap-services</filename><indexterm><primary><filename>nmap-services</filename></primary></indexterm>
database of about 2,200
well-known services,<indexterm><primary>well-known ports</primary></indexterm>
Nmap would report that those ports probably correspond to a
mail server (SMTP), web server (HTTP), and name server (DNS)
respectively. This lookup is usually accurate&mdash;the vast
majority of daemons listening on TCP port 25 are, in fact, mail
servers. However, you should not bet your security on this!
People can and do run services on strange ports.
<indexterm><primary>non-standard ports</primary></indexterm>
People can and do run services on
strange ports.<indexterm><primary>non-standard ports</primary></indexterm>
</para>
<para>Even if Nmap is right, and the hypothetical server above is
@@ -1676,8 +1662,7 @@ way.</para>
<para>After TCP and/or UDP ports are discovered using one of the
other scan methods, version detection interrogates those ports to
determine more about what is actually running. The
<filename>nmap-service-probes</filename>
<indexterm><primary><filename>nmap-service-probes</filename></primary></indexterm>
<filename>nmap-service-probes</filename><indexterm><primary><filename>nmap-service-probes</filename></primary></indexterm>
database contains probes
for querying various services and match expressions to recognize
and parse responses. Nmap tries to determine the service protocol
@@ -1689,12 +1674,10 @@ way.</para>
version, or the KaZaA user name). Of course, most services don't
provide all of this information. If Nmap was compiled with
OpenSSL support, it will connect to SSL servers to deduce the
service listening behind that encryption layer.
<indexterm><primary>SSL</primary><secondary>in version detection</secondary></indexterm>
service listening behind that encryption layer.<indexterm><primary>SSL</primary><secondary>in version detection</secondary></indexterm>
When RPC services are
discovered, the Nmap RPC grinder (<option>-sR</option>)
<indexterm><primary>RPC grinder</primary></indexterm>
<indexterm><primary><option>-sR</option></primary></indexterm>
discovered, the Nmap RPC grinder<indexterm><primary>RPC grinder</primary></indexterm>
(<option>-sR</option>)<indexterm><primary><option>-sR</option></primary></indexterm>
is automatically used to determine the RPC program and version
numbers. Some UDP ports are left in the
<literal>open|filtered</literal> state after a UDP port scan is
@@ -1720,8 +1703,7 @@ way.</para>
on the port. Please take a couple minutes to make the submission
so that your find can benefit everyone. Thanks to these
submissions, Nmap has about 3,000 pattern matches for more than
350 protocols such as SMTP, FTP, HTTP, etc.
<indexterm><primary>submission of service fingerprints</primary></indexterm>
350 protocols such as SMTP, FTP, HTTP, etc.<indexterm><primary>submission of service fingerprints</primary></indexterm>
</para>
<para>Version detection is enabled and controlled with the
@@ -1851,8 +1833,8 @@ way.</para>
what program and version number they serve up. Thus you can
effectively obtain the same info as <command>rpcinfo -p</command> even if the
target's portmapper is behind a firewall (or protected by
TCP wrappers). Decoys do not currently work with RPC scan.
<indexterm><primary>decoys</primary><secondary>which scans use</secondary></indexterm>
TCP wrappers). Decoys do not currently work with
RPC scan.<indexterm><primary>decoys</primary><secondary>which scans use</secondary></indexterm>
This is automatically enabled as part of version scan
(<option>-sV</option>) if you request that. As version
detection includes this and is much more comprehensive,
@@ -1875,8 +1857,7 @@ way.</para>
in the responses. After performing dozens of tests such as TCP
ISN sampling, TCP options support and ordering, IP ID sampling, and
the initial window size check, Nmap compares the results to its
<filename>nmap-os-db</filename>
<indexterm><primary><filename>nmap-os-db</filename></primary></indexterm>
<filename>nmap-os-db</filename><indexterm><primary><filename>nmap-os-db</filename></primary></indexterm>
database of more than a thousand known
OS fingerprints and prints out the OS details if there is a match.
Each fingerprint includes a freeform textual description of the
@@ -2083,8 +2064,8 @@ way.</para>
To reflect those different uses and to simplify the choice of which
scripts to run, each script contains a field associating it with one or more
of the above mentioned categories. To maintain the matching from scripts to
categories a file called <filename>script.db</filename>
<indexterm><primary><filename>script.db</filename></primary></indexterm>
categories a file called
<filename>script.db</filename><indexterm><primary><filename>script.db</filename></primary></indexterm>
is installed along
with the distributed scripts. Therefore, if you, for example, want to see if
a machine is infected by any worm Nmap provides a script for you can simply
@@ -2099,12 +2080,11 @@ way.</para>
An NSE script basically is a chunk of Lua-code which has (among some
informational fields, like name, id and categories) 2 functions: a test
whether the particular script should be run against a certain host or port
(called a <literal>hostrule</literal>
<indexterm><primary><varname>hostrule</varname> script variable</primary></indexterm>
or <literal>portrule</literal>
<indexterm><primary><varname>portrule</varname> script variable</primary></indexterm>
respectively) and an <literal>action</literal>
<indexterm><primary><varname>action</varname> script variable</primary></indexterm>
(called a
<literal>hostrule</literal><indexterm><primary><varname>hostrule</varname> script variable</primary></indexterm>
or <literal>portrule</literal><indexterm><primary><varname>portrule</varname> script variable</primary></indexterm>
respectively) and an
<literal>action</literal><indexterm><primary><varname>action</varname> script variable</primary></indexterm>
to be carried out if the test
returns true. Scripts have access to most information gathered by Nmap
during earlier stages. For each host this includes the IP address, hostname and (if
@@ -2142,14 +2122,10 @@ way.</para>
<listitem>
<para>Runs a script scan (like <option>-sC</option>) with the scripts you have chosen rather than the defaults. Arguments can be script categories, single scripts or directories with scripts which are to be run against the target hosts instead of the default set. Nmap will try to interpret the arguments at first as categories and afterwards as files or directories. Absolute paths are used as is, relative paths are searched in the following places until found:
<indexterm><primary><option>--datadir</option></primary></indexterm>
<filename>--datadir/</filename>;
<indexterm><primary><envar>NMAPDIR</envar> environment variable</primary></indexterm>
<filename>$NMAPDIR/</filename>;
<filename>~/.nmap/</filename> (not searched on Windows);
<indexterm><primary sortas="nmap"><filename>.nmap</filename> directory</primary></indexterm>
<indexterm><primary>NMAPDATADIR</primary></indexterm>
NMAPDATADIR/ or
<filename>--datadir/</filename>;<indexterm><primary><option>--datadir</option></primary></indexterm>
<filename>$NMAPDIR/</filename>;<indexterm><primary><envar>NMAPDIR</envar> environment variable</primary></indexterm>
<filename>~/.nmap/</filename> (not searched on Windows);<indexterm><primary sortas="nmap"><filename>.nmap</filename> directory</primary></indexterm>
NMAPDATADIR/ or<indexterm><primary>NMAPDATADIR</primary></indexterm>
<filename>./</filename>. A <filename>scripts/</filename> subdirectory is also tried in each of these. Give the argument <literal>all</literal> to execute all scripts in the Nmap script database.
</para>
@@ -2174,7 +2150,6 @@ categories.</para>
<varlistentry>
<term><option>--script-args &lt;name1=value1,name2={name3=value3},name4=value4&gt;</option>
<indexterm significance="preferred"><primary><option>--script-args</option></primary></indexterm>
<indexterm><primary>script arguments</primary></indexterm>
<indexterm><primary>script arguments</primary><seealso><option>--script-args</option></seealso></indexterm></term>
<listitem>
@@ -2387,8 +2362,8 @@ timing out and retransmitting while the response is in transit.</para>
<para>If all the hosts are on a local network, 100 milliseconds is a
reasonable aggressive <option>--max-rtt-timeout</option> value. If
routing is involved, ping a host on the network first with the ICMP
ping utility, or with a custom packet crafter such as <command>hping2</command>
<indexterm><primary><command>hping2</command></primary></indexterm>
ping utility, or with a custom packet crafter such as
<command>hping2</command><indexterm><primary><command>hping2</command></primary></indexterm>
that is
more likely to get through a firewall. Look at the maximum round trip
time out of ten packets or so. You might want to double that for the
@@ -2401,9 +2376,8 @@ exceed 1000&nbsp;ms.</para>
could be useful when a network is so unreliable that even Nmap's
default is too aggressive. Since Nmap only reduces the timeout down to
the minimum when the network seems to be reliable, this need is
unusual and should be reported as a bug to the <citetitle>nmap-dev</citetitle> mailing
list.
<indexterm><primary><citetitle>nmap-dev</citetitle> mailing list</primary></indexterm>
unusual and should be reported as a bug to the
<citetitle>nmap-dev</citetitle> mailing list.<indexterm><primary><citetitle>nmap-dev</citetitle> mailing list</primary></indexterm>
</para>
</listitem>
@@ -2502,8 +2476,8 @@ packet retransmissions and possible missed ports when the target
implements strict rate limiting.</para>
<para>Another use of <option>--scan-delay</option> is to evade
threshold based intrusion detection and prevention systems (IDS/IPS).
<indexterm><primary>intrusion detection systems</primary><secondary>evading</secondary></indexterm>
threshold based intrusion detection and prevention systems
(IDS/IPS).<indexterm><primary>intrusion detection systems</primary><secondary>evading</secondary></indexterm>
</para>
</listitem>
@@ -2544,9 +2518,7 @@ faster than a network can support may lead to a loss of accuracy. In
some cases, using a faster rate can make a scan take
<emphasis>longer</emphasis> than it would with a slower rate. This is
because Nmap's adaptive
retransmission
<indexterm><primary>adaptive retransmission</primary><see>retransmission</see></indexterm>
<indexterm><primary>retransmission</primary></indexterm>
retransmission<indexterm><primary>adaptive retransmission</primary><see>retransmission</see></indexterm><indexterm><primary>retransmission</primary></indexterm>
will detect the network congestion caused by an excessive scanning rate
and increase the number of retransmissions in order to improve accuracy.
So even though packets are sent at a higher rate, more packets are sent
@@ -2568,9 +2540,10 @@ timing.</para>
<indexterm><primary><option>--defeat-rst-ratelimit</option></primary></indexterm></term>
<listitem>
<para>Many hosts have long used rate limiting to reduce the number
<para>Many hosts have long used
rate limiting<indexterm><primary>rate limiting</primary></indexterm>
to reduce the number
of ICMP error messages (such as port-unreachable errors) they send.
<indexterm><primary>rate limiting</primary></indexterm>
Some systems now apply similar rate limits to the RST (reset)
packets they generate. This can slow Nmap down dramatically as it
adjusts its timing to reflect those rate limits. You can tell Nmap to
@@ -2597,7 +2570,6 @@ worth the extra time.</para>
&lt;paranoid|sneaky|polite|normal|aggressive|insane&gt;</option>
(Set a timing template)
<indexterm><primary><option>-T</option></primary></indexterm>
<indexterm><primary>timing templates</primary></indexterm>
<indexterm><primary>timing templates</primary><seealso><literal>paranoid</literal>, <literal>sneaky</literal>, <literal>polite</literal>, <literal>normal</literal>, <literal>aggressive</literal>, and <literal>insane</literal></seealso></indexterm>
</term>
<listitem>
@@ -2615,20 +2587,14 @@ Moreover, choosing the appropriate values can sometimes take more time
than the scan you are trying to optimize. So Nmap offers a simpler
approach, with six timing templates. You can specify them with the
<option>-T</option> option and their number (0&ndash;5) or their name.
The template names are <option>paranoid</option>&nbsp;(<option>0</option>),
<indexterm><primary><literal>paranoid</literal> (<option>-T0</option>) timing template</primary></indexterm>
<option>sneaky</option>&nbsp;(<option>1</option>),
<indexterm><primary><literal>sneaky</literal> (<option>-T1</option>) timing template</primary></indexterm>
<option>polite</option>&nbsp;(<option>2</option>),
<indexterm><primary><literal>polite</literal> (<option>-T2</option>) timing template</primary></indexterm>
<option>normal</option>&nbsp;(<option>3</option>),
<indexterm><primary><literal>normal</literal> (<option>-T3</option>) timing template</primary></indexterm>
<option>aggressive</option>&nbsp;(<option>4</option>), and
<indexterm><primary><literal>aggressive</literal> (<option>-T4</option>) timing template</primary></indexterm>
<option>insane</option>&nbsp;(<option>5</option>).
<indexterm><primary><literal>insane</literal> (<option>-T5</option>) timing template</primary></indexterm>
The template names are
<option>paranoid</option>&nbsp;(<option>0</option>),<indexterm><primary><literal>paranoid</literal> (<option>-T0</option>) timing template</primary></indexterm>
<option>sneaky</option>&nbsp;(<option>1</option>),<indexterm><primary><literal>sneaky</literal> (<option>-T1</option>) timing template</primary></indexterm>
<option>polite</option>&nbsp;(<option>2</option>),<indexterm><primary><literal>polite</literal> (<option>-T2</option>) timing template</primary></indexterm>
<option>normal</option>&nbsp;(<option>3</option>),<indexterm><primary><literal>normal</literal> (<option>-T3</option>) timing template</primary></indexterm>
<option>aggressive</option>&nbsp;(<option>4</option>),<indexterm><primary><literal>aggressive</literal> (<option>-T4</option>) timing template</primary></indexterm>
and <option>insane</option>&nbsp;(<option>5</option>).<indexterm><primary><literal>insane</literal> (<option>-T5</option>) timing template</primary></indexterm>
The first two are for IDS evasion.
<indexterm><primary>intrusion detection systems</primary><secondary>evading</secondary></indexterm>
Polite mode slows down the scan to use less bandwidth
and target machine resources. Normal mode is the default and so
<option>-T3</option> does nothing. Aggressive mode speeds scans up by
@@ -2641,11 +2607,9 @@ for speed.</para>
wish to be, while leaving Nmap to pick the exact timing values. The
templates also make some minor speed adjustments for which
fine-grained control options do not currently exist. For example,
<option>-T4</option>
<indexterm><primary><literal>aggressive</literal> (<option>-T4</option>) timing template</primary></indexterm>
<option>-T4</option><indexterm><primary><literal>aggressive</literal> (<option>-T4</option>) timing template</primary></indexterm>
prohibits the dynamic scan delay from exceeding
10&nbsp;ms for TCP ports and <option>-T5</option> caps that value at 5&nbsp;ms.
<indexterm><primary><literal>insane</literal> (<option>-T5</option>) timing template</primary></indexterm>
Templates can be used in combination with fine-grained
controls, and the fine-grained controls will you specify will take
precedence over the timing template default for that parameter. I
@@ -2660,8 +2624,7 @@ recommend always using <option>-T4</option>. Some people love
sometimes specify <option>-T2</option> because they think it is less
likely to crash hosts or because they consider themselves to be polite
in general. They often don't realize just how slow <option>-T
polite</option>
<indexterm><primary><literal>polite</literal> (<option>-T2</option>) timing template</primary></indexterm>
polite</option><indexterm><primary><literal>polite</literal> (<option>-T2</option>) timing template</primary></indexterm>
really is. Their scan may take ten times longer than a
default scan.
Machine crashes and bandwidth problems are rare with the
@@ -2670,10 +2633,9 @@ recommend that for cautious scanners. Omitting version detection is
far more effective than playing with timing values at reducing these
problems.</para>
<para>While <option>-T0</option>
<indexterm><primary><literal>paranoid</literal> (<option>-T0</option>) timing template</primary></indexterm>
and <option>-T1</option>
<indexterm><primary><literal>sneaky</literal> (<option>-T1</option>) timing template</primary></indexterm>
<para>While
<option>-T0</option><indexterm><primary><literal>paranoid</literal> (<option>-T0</option>) timing template</primary></indexterm>
and <option>-T1</option><indexterm><primary><literal>sneaky</literal> (<option>-T1</option>) timing template</primary></indexterm>
may be
useful for avoiding IDS alerts, they will take an extraordinarily long
time to scan thousands of machines or ports. For such a long scan,
@@ -2686,14 +2648,12 @@ so only one port is scanned at a time, and waiting five minutes
between sending each probe. <option>T1</option> and
<option>T2</option> are similar but they only wait 15 seconds and 0.4
seconds, respectively, between probes. <option>T3</option> is Nmap's
default behavior, which includes parallelization.
<indexterm><primary><literal>normal</literal> (<option>-T3</option>) timing template</primary></indexterm>
default behavior, which includes
parallelization.<indexterm><primary><literal>normal</literal> (<option>-T3</option>) timing template</primary></indexterm>
<option>-T4</option>
<indexterm><primary><literal>aggressive</literal> (<option>-T4</option>) timing template</primary></indexterm>
does the equivalent of <option>--max-rtt-timeout 1250
--initial-rtt-timeout 500 --max-retries 6</option> and sets the maximum TCP scan delay
to 10 milliseconds. <option>T5</option>
<indexterm><primary><literal>insane</literal> (<option>-T5</option>) timing template</primary></indexterm>
does the equivalent of
<option>--max-rtt-timeout 300 --min-rtt-timeout 50
--initial-rtt-timeout 250 --max-retries 2 --host-timeout 15m</option> as well as
@@ -2744,8 +2704,8 @@ increasingly monitoring traffic with intrusion detection systems
(IDS). All of the major IDSs ship with rules designed to detect Nmap
scans because scans are sometimes a precursor to attacks. Many of
these products have recently morphed into intrusion
<emphasis>prevention</emphasis> systems (IPS)
<indexterm><primary>intrusion prevention systems</primary><seealso>intrusion detection systems</seealso></indexterm>
<emphasis>prevention</emphasis> systems
(IPS)<indexterm><primary>intrusion prevention systems</primary><seealso>intrusion detection systems</seealso></indexterm>
that actively block
traffic deemed malicious. Unfortunately for network administrators
and IDS vendors, reliably detecting bad intentions by analyzing packet
@@ -2796,8 +2756,7 @@ lists the relevant options and describes what they do.</para>
packets. Two with eight bytes of the TCP header, and one
with the final four. Of course each fragment also has an
IP header. Specify <option>-f</option> again to use 16 bytes per fragment
(reducing the number of fragments).
<indexterm><primary><option>-f</option></primary><secondary>giving twice for small fragments</secondary></indexterm>
(reducing the number of fragments).<indexterm><primary><option>-f</option></primary><secondary>giving twice</secondary></indexterm>
Or you can specify
your own offset size with the <option>--mtu</option> option. Don't also
specify <option>-f</option> if you use <option>--mtu</option>. The offset must be a
@@ -2809,14 +2768,14 @@ lists the relevant options and describes what they do.</para>
this because fragments may take different routes into their
networks. Some source
systems defragment outgoing packets in the kernel. Linux
with the iptables
<indexterm><primary>iptables</primary></indexterm>
with the
iptables<indexterm><primary>iptables</primary></indexterm>
connection tracking module is one such
example. Do a scan while a sniffer such as <application>Wireshark</application>
<indexterm><primary><application>Wireshark</application></primary></indexterm>
example. Do a scan while a sniffer such as
<application>Wireshark</application><indexterm><primary><application>Wireshark</application></primary></indexterm>
is running to ensure that sent packets are fragmented. If your host
OS is causing problems, try the <option>--send-eth</option>
<indexterm><primary><option>--send-eth</option></primary></indexterm>
OS is causing problems, try the
<option>--send-eth</option><indexterm><primary><option>--send-eth</option></primary></indexterm>
option to bypass the IP layer and send raw ethernet frames.</para>
</listitem>
</varlistentry>
@@ -2840,19 +2799,18 @@ lists the relevant options and describes what they do.</para>
hiding your IP address.</para>
<para>Separate each decoy host with commas, and you can
optionally use <literal>ME</literal>
<indexterm><primary><literal>ME</literal> (decoy address)</primary></indexterm>
optionally use
<literal>ME</literal><indexterm><primary><literal>ME</literal> (decoy address)</primary></indexterm>
as one of the decoys to
represent the position for your real IP address. If you put
<literal>ME</literal> in the 6th position or later, some
common port scan detectors (such as Solar Designer's
<indexterm><primary>Solar Designer</primary></indexterm>
excellent Scanlogd)
<indexterm><primary><application>Scanlogd</application></primary></indexterm>
common port scan detectors (such as
Solar Designer's<indexterm><primary>Solar Designer</primary></indexterm>
excellent Scanlogd)<indexterm><primary><application>Scanlogd</application></primary></indexterm>
are unlikely to show your IP address at
all. If you don't use <literal>ME</literal>, Nmap will put
you in a random position. You can also use <literal>RND</literal>
<indexterm><primary><literal>RND</literal> (decoy address)</primary></indexterm>
you in a random position. You can also use
<literal>RND</literal><indexterm><primary><literal>RND</literal> (decoy address)</primary></indexterm>
to generate
a random, non-reserved IP address, or <literal>RND:<replaceable>number</replaceable></literal> to
generate <replaceable>number</replaceable> addresses.</para> <para>Note that the hosts
@@ -2912,7 +2870,7 @@ lists the relevant options and describes what they do.</para>
<term>
<option>-e &lt;interface&gt;</option> (Use specified interface)
<indexterm><primary><option>-e</option></primary></indexterm>
<indexterm><primary>interface</primary></indexterm>
<indexterm><primary>interface</primary><seealso><option>-e</option></seealso></indexterm>
</term>
<listitem>
@@ -2987,8 +2945,7 @@ support the option completely, as does UDP scan.</para>
bytes and ICMP echo requests are just 28. This option
tells Nmap to append the given number of random bytes to
most of the packets it sends. OS detection (<option>-O</option>) packets
are not affected
<indexterm><primary><option>--data-length</option></primary><secondary>no effect in OS detection</secondary></indexterm>
are not affected<indexterm><primary><option>--data-length</option></primary><secondary>no effect in OS detection</secondary></indexterm>
because accuracy there requires probe consistency, but most pinging and portscan packets
support this. It slows things down a little, but can make a scan slightly less
conspicuous.</para>
@@ -3029,13 +2986,11 @@ support the option completely, as does UDP scan.</para>
<para>Nmap also offers a shortcut mechanism for specifying
options. Simply pass the letter <literal>R</literal>,
<literal>T</literal>, or <literal>U</literal> to request
record-route,
<indexterm><primary>record route IP option</primary></indexterm>
record-timestamp,
<indexterm><primary>record timestamp IP option</primary></indexterm>
record-route,<indexterm><primary>record route IP option</primary></indexterm>
record-timestamp,<indexterm><primary>record timestamp IP option</primary></indexterm>
or both options together,
respectively. Loose or strict source routing
<indexterm><primary>source routing</primary></indexterm>
respectively.
Loose or strict source routing<indexterm><primary>source routing</primary></indexterm>
may be specified
with an <literal>L</literal> or <literal>S</literal> followed by
a space and then a space-separated list of IP addresses.</para>
@@ -3075,17 +3030,14 @@ support the option completely, as does UDP scan.</para>
to various network monitoring systems, especially when you
combine it with slow timing options. If you
want to randomize over larger group sizes, increase
PING_GROUP_SZ
<indexterm><primary><varname>PING_GROUP_SZ</varname></primary></indexterm>
in <filename>nmap.h</filename>
<indexterm><primary><filename>nmap.h</filename></primary></indexterm>
<varname>PING_GROUP_SZ</varname><indexterm><primary><varname>PING_GROUP_SZ</varname></primary></indexterm>
in <filename>nmap.h</filename><indexterm><primary><filename>nmap.h</filename></primary></indexterm>
and recompile.
An alternative solution is to generate the target IP list
with a list scan (<option>-sL -n -oN
<replaceable>filename</replaceable></option>), randomize it
with a Perl script, then provide the whole list to Nmap with
<option>-iL</option>.
<indexterm><primary><option>-iL</option></primary><secondary>randomizing hosts with</secondary></indexterm>
<option>-iL</option>.<indexterm><primary><option>-iL</option></primary><secondary>randomizing hosts with</secondary></indexterm>
</para>
</listitem>
</varlistentry>
@@ -3102,8 +3054,7 @@ support the option completely, as does UDP scan.</para>
<para>Asks Nmap to use the given MAC address
<indexterm><primary>MAC address</primary></indexterm>
for all of the raw ethernet frames it sends. This option implies
<option>--send-eth</option>
<indexterm><primary><option>--send-eth</option></primary><secondary>implied by <option>--spoof-mac</option></secondary></indexterm>
<option>--send-eth</option><indexterm><primary><option>--send-eth</option></primary><secondary>implied by <option>--spoof-mac</option></secondary></indexterm>
to ensure that Nmap actually sends
ethernet-level packets. The MAC given can take several formats. If
it is simply the number <literal>0</literal>, Nmap chooses a completely random MAC address
@@ -3114,9 +3065,7 @@ support the option completely, as does UDP scan.</para>
argument isn't a 0 or hex string, Nmap looks through
<filename>nmap-mac-prefixes</filename> to find a vendor name containing the given string
(it is case insensitive). If a match is found, Nmap uses the
vendor's OUI (3-byte prefix)
<indexterm><primary>organizationally unique identifier (OUI)</primary></indexterm>
<indexterm><primary>organizationally unique identifier (OUI)</primary><seealso><filename>nmap-mac-prefixes</filename></seealso></indexterm>
vendor's OUI (3-byte prefix)<indexterm><primary>organizationally unique identifier (OUI)</primary></indexterm><indexterm><primary>organizationally unique identifier (OUI)</primary><seealso><filename>nmap-mac-prefixes</filename></seealso></indexterm>
and fills out the remaining 3 bytes
randomly. Valid <option>--spoof-mac</option> argument examples are <literal>Apple</literal>, <literal>0</literal>,
<literal>01:02:03:04:05:06</literal>, <literal>deadbeefcafe</literal>, <literal>0020F2</literal>, and <literal>Cisco</literal>. This option only affects raw packet scans such as SYN scan or OS detection, not connection-oriented features such as version detection or the Nmap Scripting Engine.</para>
@@ -3168,29 +3117,26 @@ files, which Nmap can append to or clobber. Output files may also be
used to resume aborted scans.</para>
<para>Nmap makes output available in five different formats.
The default is called <firstterm>interactive output</firstterm>,
<indexterm><primary>interactive output</primary></indexterm>
and it is sent to standard output (stdout).
<indexterm><primary>stdout</primary></indexterm>
<indexterm><primary>standard output</primary></indexterm>
There is also <firstterm>normal output</firstterm>,
<indexterm><primary>normal output</primary></indexterm>
The default is called
<firstterm>interactive output</firstterm>,<indexterm><primary>interactive output</primary></indexterm>
and it is sent to
standard output (stdout).<indexterm><primary>stdout</primary></indexterm><indexterm><primary>standard output</primary></indexterm>
There is also
<firstterm>normal output</firstterm>,<indexterm><primary>normal output</primary></indexterm>
which is similar to interactive except that it
displays less runtime information and warnings since it is expected to
be analyzed after the scan completes rather than interactively.</para>
<para><firstterm>XML output</firstterm>
<indexterm><primary>XML output</primary></indexterm>
<para><firstterm>XML output</firstterm><indexterm><primary>XML output</primary></indexterm>
is one of the most important output types, as it can
be converted to HTML, easily parsed by programs such as Nmap graphical
user interfaces, or imported into databases.</para>
<para>The two remaining output types are the simple <firstterm>grepable
output</firstterm>
<indexterm><primary>grepable output</primary></indexterm>
<para>The two remaining output types are the simple
<firstterm>grepable output</firstterm><indexterm><primary>grepable output</primary></indexterm>
which includes most information for a target host on
a single line, and <firstterm>sCRiPt KiDDi3 0utPUt</firstterm>
<indexterm><primary sortas="script kiddie output">scR1pT kIddI3 output</primary></indexterm>
a single line, and
<firstterm>sCRiPt KiDDi3 0utPUt</firstterm><indexterm><primary sortas="script kiddie output">scR1pT kIddI3 output</primary></indexterm>
for users
who consider themselves |&lt;-r4d.</para>
@@ -3217,14 +3163,9 @@ character as the argument to one of the format types. This causes
Nmap to deactivate interactive output, and instead print
results in the format you specified to the standard output stream. So the
command <command>nmap -oX - target</command> will send only XML output to
stdout.
<indexterm><primary>stdout</primary></indexterm>
<indexterm><primary>standard output</primary></indexterm>
<indexterm><primary>output</primary><secondary>to stdout with <literal>-</literal></secondary></indexterm>
stdout.<indexterm><primary>output</primary><secondary>to stdout with <literal>-</literal></secondary></indexterm>
Serious errors may still be printed to the normal error
stream, stderr.
<indexterm><primary>standard error</primary></indexterm>
<indexterm><primary>stderr</primary></indexterm>
stream, stderr.<indexterm><primary>standard error</primary></indexterm><indexterm><primary>stderr</primary></indexterm>
</para>
<para>Unlike some Nmap arguments, the space between the logfile option
@@ -3236,8 +3177,8 @@ compatibility feature of Nmap will cause the creation of
<filename>G-</filename> and <filename>Xscan.xml</filename>
respectively.</para>
<para>All of these arguments support <function>strftime()</function>-like
<indexterm><primary><function>strftime</function> conversions in filenames</primary></indexterm>
<para>All of these arguments support
<function>strftime()</function>-like<indexterm><primary><function>strftime</function> conversions in filenames</primary></indexterm>
conversions in the filename. <literal>%H</literal>, <literal>%M</literal>,
<literal>%S</literal>, <literal>%m</literal>, <literal>%d</literal>,
<literal>%y</literal>, and <literal>%Y</literal> are all exactly the same
@@ -3355,8 +3296,7 @@ are running Solaris takes only a simple grep to identify the hosts,
piped to an awk or cut command to print the desired fields.</para>
<para>Grepable output consists of comments (lines starting with a
pound (#))
<indexterm><primary>grepable output</primary><secondary>comments in</secondary></indexterm>
pound (#))<indexterm><primary>grepable output</primary><secondary>comments in</secondary></indexterm>
and target lines. A target line includes a combination
of 6 labeled fields, separated by tabs and followed with a colon.
The fields are <literal>Host</literal>, <literal>Ports</literal>,
@@ -3448,8 +3388,8 @@ format is available
debugging is available to flood you with much more! As with the
verbosity option (<option>-v</option>), debugging is enabled with a
command-line flag (<option>-d</option>) and the debug level can be
increased by specifying it multiple times.
<indexterm><primary><option>-d</option></primary><secondary>giving more than once</secondary></indexterm>
increased by specifying it
multiple times.<indexterm><primary><option>-d</option></primary><secondary>giving more than once</secondary></indexterm>
Alternatively, you can set
a debug level by giving an argument to <option>-d</option>. For
example, <option>-d9</option> sets level nine. That is the highest
@@ -3463,8 +3403,8 @@ self-explanatory. You may get something like: <computeroutput>Timeout
vals: srtt: -1 rttvar: -1 to: 1000000 delta 14987 ==> srtt: 14987
rttvar: 14987 to: 100000</computeroutput>. If you don't understand a line, your only recourses
are to ignore it, look it up in the source code, or request help from
the development list (<citetitle>nmap-dev</citetitle>).
<indexterm><primary><citetitle>nmap-dev</citetitle> mailing list</primary></indexterm>
the development list
(<citetitle>nmap-dev</citetitle>).<indexterm><primary><citetitle>nmap-dev</citetitle> mailing list</primary></indexterm>
Some lines are self explanatory, but
the messages become more obscure as the debug level is
increased.</para>
@@ -3713,9 +3653,8 @@ overwhelming requests. Specify <option>--open</option> to only see
configured for IPv6. If your ISP (like most of them) does
not allocate IPv6 addresses to you, free tunnel brokers are
widely available and work fine with Nmap. I use the free
IPv6 tunnel broker service at
<ulink url="http://www.tunnelbroker.net"/>.
<indexterm><primary>IPv6 tunnel broker</primary></indexterm>
IPv6 tunnel broker<indexterm><primary>IPv6 tunnel broker</primary></indexterm>
service at <ulink url="http://www.tunnelbroker.net"/>.
Other tunnel brokers are
<ulink url="http://en.wikipedia.org/wiki/List_of_IPv6_tunnel_brokers">listed
at Wikipedia</ulink>. 6to4 tunnels are another popular,
@@ -3766,15 +3705,13 @@ overwhelming requests. Specify <option>--open</option> to only see
<filename>nmap-os-db</filename>. If the
location of any of these files has been specified (using the
<option>--servicedb</option> or <option>--versiondb</option> options),
<indexterm><primary><option>--servicedb</option></primary></indexterm>
<indexterm><primary><option>--versiondb</option></primary></indexterm>
that location is used for that file. After that, Nmap
searches these files in the directory specified with the
<option>--datadir</option> option (if any). Any files not
found there, are searched for in the directory specified by
the NMAPDIR environmental variable<indexterm><primary><envar>NMAPDIR</envar> environment variable</primary></indexterm>.
Next comes <filename>~/.nmap</filename>
<indexterm><primary sortas="nmap"><filename>.nmap</filename> directory</primary></indexterm>
Next comes
<filename>~/.nmap</filename><indexterm><primary sortas="nmap"><filename>.nmap</filename> directory</primary></indexterm>
for real and effective UIDs (POSIX systems only) or location of
the Nmap executable (Win32 only), and then a compiled-in
location such as <filename>/usr/local/share/nmap</filename> or <filename>/usr/share/nmap</filename>
@@ -3824,8 +3761,8 @@ overwhelming requests. Specify <option>--open</option> to only see
<para>Asks Nmap to send packets at the raw ethernet (data
link) layer rather than the higher IP (network) layer. By
default, Nmap chooses the one which is generally best for
the platform it is running on. Raw sockets (IP layer)
<indexterm><primary>raw sockets</primary></indexterm>
the platform it is running on.
Raw sockets (IP layer)<indexterm><primary>raw sockets</primary></indexterm>
are
generally most efficient for Unix machines, while ethernet
frames are required for Windows operation since Microsoft
@@ -3859,9 +3796,8 @@ overwhelming requests. Specify <option>--open</option> to only see
<para>Tells Nmap to simply assume that it is privileged
enough to perform raw socket sends, packet sniffing, and
similar operations that usually require root privileges
<indexterm><primary>privileged users</primary></indexterm>
<indexterm><primary>authorized users</primary><see>privileged users</see></indexterm>
similar operations that usually require
root privileges<indexterm><primary>privileged users</primary></indexterm><indexterm><primary>authorized users</primary><see>privileged users</see></indexterm>
on Unix systems. By default Nmap quits if such operations are
requested but geteuid() is not
zero. <option>--privileged</option> is useful with Linux
@@ -3869,8 +3805,9 @@ overwhelming requests. Specify <option>--open</option> to only see
configured to allow unprivileged users to perform raw-packet
scans. Be sure to provide this option flag before any flags
for options that require privileges (SYN scan, OS detection,
etc.). The <envar>NMAP_PRIVILEGED</envar> environmental variable
<indexterm><primary><envar>NMAP_PRIVILEGED</envar> environment variable</primary></indexterm>
etc.). The
<envar>NMAP_PRIVILEGED</envar><indexterm><primary><envar>NMAP_PRIVILEGED</envar> environment variable</primary></indexterm>
environmental variable
may be set as an equivalent alternative to
<option>--privileged</option>.</para>
</listitem>
@@ -3888,11 +3825,11 @@ overwhelming requests. Specify <option>--open</option> to only see
<para>This option is the opposite of
<option>--privileged</option>. It tells Nmap to treat the
user as lacking network raw socket and sniffing privileges.
<indexterm><primary>unprivileged users</primary></indexterm>
This is useful for testing, debugging, or when the raw
network functionality of your operating system is somehow
broken. The <envar>NMAP_UNPRIVILEGED</envar> environmental variable
<indexterm><primary><envar>NMAP_UNPRIVILEGED</envar> environment variable</primary></indexterm>
broken. The
<envar>NMAP_UNPRIVILEGED</envar><indexterm><primary><envar>NMAP_UNPRIVILEGED</envar> environment variable</primary></indexterm>
environmental variable
may be set as an equivalent alternative to
<option>--unprivileged</option>.</para>
@@ -3935,8 +3872,8 @@ overwhelming requests. Specify <option>--open</option> to only see
help. This option is rarely used because proper shells
are usually more familiar and feature-complete. This option
includes a bang (!) operator for executing shell commands,
which is one of many reasons not to install Nmap setuid root.
<indexterm><primary>setuid, why Nmap shouldn't be</primary></indexterm>
which is one of many reasons not to install Nmap
setuid root.<indexterm><primary>setuid, why Nmap shouldn't be</primary></indexterm>
</para>
</listitem>
</varlistentry>
@@ -4098,7 +4035,6 @@ overwhelming requests. Specify <option>--open</option> to only see
probing one port on each target host anyway.</para>
<para>
<indexterm><primary><option>-PN</option></primary><secondary>example of</secondary></indexterm>
<indexterm><primary><option>-oX</option></primary><secondary>example of</secondary></indexterm>
<indexterm><primary><option>-oG</option></primary><secondary>example of</secondary></indexterm>
<command>nmap -PN -p80 -oX logs/pb-port80scan.xml -oG
@@ -4121,8 +4057,7 @@ overwhelming requests. Specify <option>--open</option> to only see
do some research to determine whether it has already been
discovered and addressed. Try Googling the error message or
browsing the <citetitle>nmap-dev</citetitle> archives at <ulink
url="http://seclists.org/" />.
<indexterm><primary><citetitle>nmap-dev</citetitle> mailing list</primary></indexterm>
url="http://seclists.org/" />.<indexterm><primary><citetitle>nmap-dev</citetitle> mailing list</primary></indexterm>
Read this full manual page as
well. If nothing comes of this, mail a bug report to
<email>nmap-dev@insecure.org</email>. Please include everything
@@ -4148,8 +4083,7 @@ overwhelming requests. Specify <option>--open</option> to only see
<para>Hundreds of people have made valuable contributions to Nmap
over the years. These are detailed in the
<filename>CHANGELOG</filename>
<indexterm><primary>changelog</primary></indexterm>
<filename>CHANGELOG</filename><indexterm><primary>changelog</primary></indexterm>
file which is distributed with Nmap
and also available from <ulink
url="http://nmap.org/changelog.html" />.</para>
@@ -4160,4 +4094,4 @@ overwhelming requests. Specify <option>--open</option> to only see
&legal-notices;
</refsect1>
</refentry>
<indexterm class="endofrange" startref="man-nmap1-indexterm"><primary>reference guide (man page)</primary></indexterm>
<indexterm class="endofrange" startref="man-nmap1-indexterm"/>

234
docs/scripting.xml
View File

@@ -13,11 +13,11 @@
growing and diverse set of scripts distributed with Nmap, or write
their own to meet custom needs.</para>
<para>The Nmap project would like to thank Diman Todorov
<indexterm><primary>Todorov, Diman</primary></indexterm>
<para>The Nmap project would like to thank
Diman Todorov<indexterm><primary>Todorov, Diman</primary></indexterm>
for his excellent work building the initial NSE implementation and
writing much of this documentation. Stoiko Ivanov
<indexterm><primary>Ivanov, Stoiko</primary></indexterm>
writing much of this documentation.
Stoiko Ivanov<indexterm><primary>Ivanov, Stoiko</primary></indexterm>
also contributed greatly. The tasks we had in mind when
creating the system are:</para>
@@ -73,8 +73,8 @@
backdoors to enable later reentry. Some of these can be
detected by Nmap's regular expression based version detection.
For example, within hours of the MyDoom worm hitting the
Internet, Jay Moran
<indexterm><primary>Moran, Jay</primary></indexterm>
Internet,
Jay Moran<indexterm><primary>Moran, Jay</primary></indexterm>
posted an Nmap version detection probe and
signature so that others could quickly scan their networks.
For more complex worms and backdoors, NSE is needed
@@ -89,12 +89,11 @@
As a general scripting language, NSE could even
be used to exploit vulnerabilities rather than just find them.
The capability to add custom exploit scripts may be valuable
for some people (particularly penetration testers),
<indexterm><primary>penetration testing</primary></indexterm>
for some people (particularly
penetration testers),<indexterm><primary>penetration testing</primary></indexterm>
though we aren't
planning to turn Nmap into an exploitation framework like
<ulink url="http://www.metasploit.com">Metasploit</ulink>.
<indexterm><primary><application>Metasploit</application></primary></indexterm>
<ulink url="http://www.metasploit.com">Metasploit</ulink>.<indexterm><primary><application>Metasploit</application></primary></indexterm>
</para>
</listitem>
</varlistentry>
@@ -108,9 +107,8 @@
<para>
Scripts are written in the
embedded <ulink url="http://www.lua.org/">Lua programming language</ulink>.
<indexterm><primary>Lua programming language</primary></indexterm>
<indexterm><primary>Lua programming language</primary><seealso>Nmap Scripting Engine</seealso></indexterm>
embedded
<ulink url="http://www.lua.org/">Lua programming language</ulink>.<indexterm><primary>Lua programming language</primary><seealso>Nmap Scripting Engine</seealso></indexterm>
The language itself is well documented in the books
<web>
<citetitle><ulink url="http://www.amazon.com/exec/obidos/ASIN/8590379825/secbks-20">Programming
@@ -133,15 +131,14 @@ The reference manual is also
</para>
<para>
NSE is activated with the <option>-sC</option>
<indexterm><primary><option>-sC</option></primary></indexterm>
option (or <option>--script</option>
<indexterm><primary><option>--script</option></primary></indexterm>
NSE is activated with the
<option>-sC</option><indexterm><primary><option>-sC</option></primary></indexterm>
option (or
<option>--script</option><indexterm><primary><option>--script</option></primary></indexterm>
if you wish to specify a custom set of
scripts) and results are integrated into Nmap normal
<indexterm><primary>normal output</primary></indexterm>
and XML output.
<indexterm><primary>XML output</primary></indexterm>
scripts) and results are integrated into Nmap
normal<indexterm><primary>normal output</primary></indexterm>
and XML output.<indexterm><primary>XML output</primary></indexterm>
Two types of scripts are supported: service and host
scripts. Service scripts relate to a certain open port
(service) on the target host, and any results they produce are included
@@ -157,8 +154,8 @@ The reference manual is also
username it is running under, and <literal>HTML Title</literal>,
which simply grabs the title of the root path of any web servers
found. A sample host script is <literal>RIPE Query</literal>,
which looks up and reports target IP ownership information.
<indexterm><primary>script names, examples of</primary></indexterm>
which looks up and reports target IP ownership
information.<indexterm><primary>script names, examples of</primary></indexterm>
</para>
<example id="nse-ex1">
@@ -190,21 +187,18 @@ Nmap finished: 1 IP address (1 host up) scanned in 0.907 seconds
<title>Usage and Examples</title>
<para>
While NSE has a complex implementation for efficiency, it is
strikingly easy to use. Simply specify <option>-sC</option>
<indexterm><primary><option>-sC</option></primary></indexterm>
strikingly easy to use. Simply specify
<option>-sC</option><indexterm><primary><option>-sC</option></primary></indexterm>
to enable the most common scripts. Or specify the
<option>--script</option>
<indexterm><primary><option>--script</option></primary></indexterm>
<option>--script</option><indexterm><primary><option>--script</option></primary></indexterm>
option to choose your own scripts to
execute by providing categories, script file names, or the name of
directories full of scripts you wish to execute. You can customize
some scripts by providing arguments to them via the
<option>--script-args</option>
<indexterm><primary><option>--script-args</option></primary></indexterm>
option. The two remaining options, <option>--script-trace</option>
<indexterm><primary><option>--script-trace</option></primary></indexterm>
and <option>--script-updatedb</option>,
<indexterm><primary><option>--script-updatedb</option></primary></indexterm>
<option>--script-args</option><indexterm><primary><option>--script-args</option></primary></indexterm>
option. The two remaining options,
<option>--script-trace</option><indexterm><primary><option>--script-trace</option></primary></indexterm>
and <option>--script-updatedb</option>,<indexterm><primary><option>--script-updatedb</option></primary></indexterm>
are generally only used for script debugging and development.
</para>
@@ -408,16 +402,12 @@ with scripts which
are to be run against the target hosts instead of the default set. Nmap
will try to interpret the arguments at first as categories and afterwards
as files or directories. Absolute paths are used as is, relative paths are
searched in the following places until found:
<indexterm><primary>data files</primary><secondary>directory search order</secondary></indexterm>
<indexterm><primary>scripts, location of</primary></indexterm>
searched in the following places until
found:<indexterm><primary>data files</primary><secondary>directory search order</secondary></indexterm><indexterm><primary>scripts, location of</primary></indexterm>
<filename>--datadir/</filename>;
<indexterm><primary><envar>NMAPDIR</envar> environment variable</primary></indexterm>
<filename>$NMAPDIR/</filename>;
<indexterm><primary sortas="nmap"><filename>.nmap</filename> directory</primary></indexterm>
<filename>~/.nmap/</filename> (not searched on Windows);
<indexterm><primary>NMAPDATADIR</primary></indexterm>
NMAPDATADIR/ or
<filename>$NMAPDIR/</filename>;<indexterm><primary><envar>NMAPDIR</envar> environment variable</primary></indexterm>
<filename>~/.nmap/</filename> (not searched on Windows);<indexterm><primary sortas="nmap"><filename>.nmap</filename> directory</primary></indexterm>
NMAPDATADIR/ or<indexterm><primary>NMAPDATADIR</primary></indexterm>
<filename>./</filename>. A <filename>scripts/</filename> subdirectory
is also tried in each of these. Give the argument <literal>all</literal> to execute all scripts in the Nmap script database.
</para>
@@ -433,8 +423,7 @@ extension does not have to be <literal>nse</literal>.
<para>Nmap scripts are stored in a <filename>scripts</filename>
subdirectory of the Nmap data directory
(see <xref linkend="data-files"/>) by default. Scripts are indexed in a database stored in
<filename>scripts/script.db</filename>.
<indexterm><primary><filename>script.db</filename></primary></indexterm>
<filename>scripts/script.db</filename>.<indexterm><primary><filename>script.db</filename></primary></indexterm>
The database lists all of the
scripts in each category. A single script may be in several
categories.</para>
@@ -489,7 +478,6 @@ categories.</para>
specified with the <option>--script</option> option. For
efficiency reasons, NSE generates a
<filename>script.db</filename>
<indexterm><primary><filename>script.db</filename></primary></indexterm>
file which maps
categories to the scripts they contain. If you changed
tag directives or added/removed scripts, run
@@ -501,11 +489,11 @@ categories.</para>
<para>
Some of the Nmap options have effects on script scans. The most
prominent of these is <option>-sV</option>.
<indexterm><primary><option>-sV</option></primary></indexterm>
prominent of these is
<option>-sV</option>.<indexterm><primary><option>-sV</option></primary></indexterm>
A version scan executes
the scripts in the <literal>version</literal> category.
<indexterm><primary><literal>version</literal> script category</primary></indexterm>
the scripts in the
<literal>version</literal> category.<indexterm><primary><literal>version</literal> script category</primary></indexterm>
The scripts
in this category are slightly different than other scripts. Their
output blends in with the version scan and they do not produce any
@@ -513,8 +501,7 @@ categories.</para>
</para>
<para>
Another option which has effect on the scripting engine is
<option>-A</option>.
<indexterm><primary><option>-A</option></primary><secondary>features enabled by</secondary></indexterm>
<option>-A</option>.<indexterm><primary><option>-A</option></primary><secondary>features enabled by</secondary></indexterm>
The advanced/aggressive mode of Nmap implies
the option <option>-sC</option>.
</para>
@@ -560,8 +547,7 @@ categories.</para>
should be kept short to conserve space in Nmap output, while
still being meaningful enough for users to recognize. Some
good examples are <literal>RIPE query</literal>, <literal>HTML
title</literal>, and <literal>Kibuv worm</literal>.
<indexterm><primary>script names, examples of</primary></indexterm>
title</literal>, and <literal>Kibuv worm</literal>.<indexterm><primary>script names, examples of</primary></indexterm>
</para>
</sect2>
<sect2 id="nse-format-description">
@@ -647,11 +633,9 @@ that.</para>
evaluates to <literal>true</literal>, the script action
is performed. Otherwise the action is skipped. Port rules are
only matched against TCP or UDP ports in the
<literal>open</literal>, <literal>open|filtered</literal> or
<literal>unfiltered</literal>
<indexterm><primary><literal>open</literal> port state</primary></indexterm>
<indexterm><primary><literal>open|filtered</literal> port state</primary></indexterm>
<indexterm><primary><literal>unfiltered</literal> port state</primary></indexterm>
<literal>open</literal>,<indexterm><primary><literal>open</literal> port state</primary></indexterm>
<literal>open|filtered</literal> or<indexterm><primary><literal>open|filtered</literal> port state</primary></indexterm>
<literal>unfiltered</literal><indexterm><primary><literal>unfiltered</literal> port state</primary></indexterm>
states. Host rules are matched exactly once against every
scanned host. The action, like the rule, is a Lua function,
which takes a host and port table as arguments. If the script is
@@ -717,8 +701,7 @@ that.</para>
extended with libraries for interfacing with Nmap. The Nmap
API is in the Lua namespace <literal>nmap</literal>. This
means that all calls to resources provided by Nmap have an
<literal>nmap</literal> prefix.
<indexterm><primary><varname>nmap</varname> NSE module</primary></indexterm>
<literal>nmap</literal> prefix.<indexterm><primary><varname>nmap</varname> NSE module</primary></indexterm>
<literal>nmap.new_socket()</literal>, for example, returns a
new socket wrapper object. The Nmap library layer also takes
care of initializing the Lua context, scheduling parallel
@@ -774,12 +757,11 @@ that.</para>
<title>Bitwise Logical Operations</title>
<indexterm><primary><varname>bit</varname> NSE module</primary></indexterm>
<para>
Lua does not provide bitwise logical operations.
<indexterm><primary>bitwise operations in NSE</primary></indexterm>
Lua does not provide
bitwise logical operations.<indexterm><primary>bitwise operations in NSE</primary></indexterm>
Since they
are often useful for low-level network communication, Reuben
Thomas'
<indexterm><primary>Thomas, Reuben</primary></indexterm>
are often useful for low-level network communication,
Reuben Thomas'<indexterm><primary>Thomas, Reuben</primary></indexterm>
<ulink url="http://luaforge.net/projects/bitlib">bitwise operation library</ulink>
for Lua has been
integrated into NSE. The arguments to the bitwise operation
@@ -897,8 +879,7 @@ that.</para>
functionality Lua provides, it's not very convenient. Therefore the
BinLib has been added to NSE, based on
<ulink url="http://www.tecgraf.puc-rio.br/~lhf/ftp/lua/">lpack</ulink>
by Luiz Henrique de Figueiredo.
<indexterm><primary>Henrique de Figueiredo, Luiz</primary></indexterm>
by Luiz Henrique de Figueiredo.<indexterm><primary>Henrique de Figueiredo, Luiz</primary></indexterm>
The BinLib functions take a format string to encode and decode binary
data. The operators of the format string are shown in <xref linkend="scripting-tbl-binlib"/>.</para>
@@ -989,10 +970,8 @@ that.</para>
powerful as standard regular expressions. So we have
integrated Perl compatible regular expressions into Lua
using PCRE and a modified version of the Lua PCRE library
written by Reuben Thomas
<indexterm><primary>Thomas, Reuben</primary></indexterm>
and Shmuel Zeigerman.
<indexterm><primary>Zeigerman, Shmuel</primary></indexterm>
written by Reuben Thomas<indexterm><primary>Thomas, Reuben</primary></indexterm>
and Shmuel Zeigerman.<indexterm><primary>Zeigerman, Shmuel</primary></indexterm>
These are
the same sort of regular expressions used by Nmap version
detection. The main modification to their library is that
@@ -1006,7 +985,6 @@ that.</para>
execution time when patterns are reused. Compiled patterns
can be cached in the NSE registry and reused by other
scripts. The PCRE functions reside inside the <literal>pcre</literal>
<indexterm><primary><varname>pcre</varname> NSE module</primary></indexterm>
namespace.
</para>
@@ -1769,7 +1747,7 @@ if(s) code_to_be_done_on_match end
<sect2 id="nse-lib-datafiles">
<title>Data File Parsing Functions</title>
<indexterm><primary><varname>datafiles</varname> NSE module</primary></indexterm>
<indexterm><primary><varname>data files</varname> access to from NSE</primary></indexterm>
<indexterm><primary>data files</primary><secondary>access to from NSE</secondary></indexterm>
<para>
The <literal>datafiles</literal> module provides functions for reading and parsing
Nmap's data files (e.g. <filename>nmap-protocol</filename>, <filename>nmap-rpc</filename>,
@@ -1937,8 +1915,8 @@ if(s) code_to_be_done_on_match end
NSE scripts have access to several Nmap facilities for writing
flexible and elegant scripts. The API provides target host
details such as port states and version detection results. It
also offers an interface to the Nsocklibrary
<indexterm><primary>Nsock</primary></indexterm>
also offers an interface to the Nsock<indexterm><primary>Nsock</primary></indexterm>
library
for efficient network I/O.
</para>
@@ -1948,8 +1926,8 @@ if(s) code_to_be_done_on_match end
An effective Nmap scripting engine requires more than just a
Lua interpreter. Users need easy access to the information
Nmap has learned about the target hosts. This data is passed
as arguments to the NSE <literal>action</literal> method.
<indexterm><primary><varname>action</varname> script variable</primary></indexterm>
as arguments to the NSE
<literal>action</literal> method.<indexterm><primary><varname>action</varname> script variable</primary></indexterm>
The arguments, <literal>host</literal> and
<literal>port</literal>, are Lua tables which contain
information on the target against which the script is
@@ -2034,8 +2012,7 @@ if(s) code_to_be_done_on_match end
<term><option>host.mac_addr</option>
</term>
<listitem>
<para>MAC address
<indexterm><primary>MAC address</primary></indexterm>
<para>MAC address<indexterm><primary>MAC address</primary></indexterm>
of the destination host (6-byte long binary
string) or <literal>nil</literal>, if the host is not directly connected.
</para>
@@ -2046,8 +2023,8 @@ if(s) code_to_be_done_on_match end
</term>
<listitem>
<para>Our own MAC address, which was used to connect to the
host (either our network card's, or (with <option>--spoof-mac</option>)
<indexterm><primary><option>--spoof-mac</option></primary></indexterm>
host (either our network card's, or (with
<option>--spoof-mac</option>)<indexterm><primary><option>--spoof-mac</option></primary></indexterm>
the spoofed address).
</para>
</listitem>
@@ -2056,8 +2033,8 @@ if(s) code_to_be_done_on_match end
<term><option>host.interface</option>
</term>
<listitem>
<para>A string containing the interface name (dnet-style)
<indexterm><primary>libdnet</primary></indexterm>
<para>A string containing the interface name
(dnet-style)<indexterm><primary>libdnet</primary></indexterm>
through
which packets to the host are sent.
</para>
@@ -2246,11 +2223,11 @@ if(s) code_to_be_done_on_match end
</term>
<listitem>
<para>
Returns the debugging level
<indexterm><primary>debugging</primary><secondary>in NSE</secondary></indexterm>
Returns the
debugging level<indexterm><primary>debugging</primary><secondary>in NSE</secondary></indexterm>
as a non-negative integer. The
debugging level can be set with the <option>-d</option>
<indexterm><primary><option>-d</option></primary></indexterm>
debugging level can be set with the
<option>-d</option><indexterm><primary><option>-d</option></primary></indexterm>
option<bookex> (see <xref linkend="port-scanning-options-output"/>)</bookex>.
</para>
</listitem>
@@ -2260,8 +2237,8 @@ if(s) code_to_be_done_on_match end
</term>
<listitem>
<para>
Returns true if Nmap was compiled with SSL support,
<indexterm><primary>SSL</primary><secondary>in NSE</secondary></indexterm>
Returns true if Nmap was compiled with
SSL support,<indexterm><primary>SSL</primary><secondary>in NSE</secondary></indexterm>
false
otherwise. This can be used to avoid sending SSL probes
when SSL is not available.
@@ -2272,11 +2249,11 @@ if(s) code_to_be_done_on_match end
<term><option>nmap.verbosity()</option></term>
<listitem>
<para>
Returns the verbosity level
<indexterm><primary>verbosity</primary><secondary>in NSE</secondary></indexterm>
Returns the
verbosity level<indexterm><primary>verbosity</primary><secondary>in NSE</secondary></indexterm>
as a non-negative integer. The
verbosity level can be set with the <option>-v</option>
<indexterm><primary><option>-v</option></primary></indexterm>
verbosity level can be set with the
<option>-v</option><indexterm><primary><option>-v</option></primary></indexterm>
option<bookex> (see <xref linkend="port-scanning-options-output"/>)</bookex>.
</para>
</listitem>
@@ -2454,8 +2431,8 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"})
</term>
<listitem>
<para>
For the provided dnet-style
<indexterm><primary>libdnet</primary></indexterm>
For the provided
dnet-style<indexterm><primary>libdnet</primary></indexterm>
<literal>interface_name</literal>,
<literal>nmap.get_interface_link()</literal> returns
what kind of link level hardware the interface
@@ -2832,10 +2809,9 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"})
NSE provides script developers with a more powerful option:
raw packet network I/O. The greater flexibility comes, however, at
the cost of a slightly more complex API. Receiving raw packets is
accomplished via a wrapper around Libpcap
<indexterm><primary>libpcap</primary></indexterm>
inside the Nsock library.
<indexterm><primary>Nsock</primary></indexterm>
accomplished via a wrapper around
Libpcap<indexterm><primary>libpcap</primary></indexterm>
inside the Nsock library.<indexterm><primary>Nsock</primary></indexterm>
In order to keep the
capturing efficient it works in a three tiered approach: Opening a
device for capturing, registering listeners to it and receiving
@@ -2924,8 +2900,8 @@ error_message describes the occurred error.</para>
<para>
Receiving raw packets is a great feature, but it is also only the
half job. Now for sending raw packets: To accomplish this NSE has
access to a wrapper around the <literal>dnet</literal> library.
<indexterm><primary>libdnet</primary></indexterm>
access to a wrapper around the
<literal>dnet</literal> library.<indexterm><primary>libdnet</primary></indexterm>
Currently NSE has the ability to send raw ethernet frames via the
following API:
</para>
@@ -2990,8 +2966,8 @@ error_message describes the occurred error.</para>
Each thread made for a script (e.g. anonFTP.nse) will yield to other
scripts whenever it makes a call on network objects (sending/receiving
data). Some scripts need finer control over threads' execution. An
example is the <literal>whois.nse</literal> script which queries whois
<indexterm><primary>whois</primary></indexterm>
example is the <literal>whois.nse</literal> script which queries
whois<indexterm><primary>whois</primary></indexterm>
servers for each target. Because many concurrent queries often result in
getting one's IP banned for abuse and a query may return additional
information for targets other threads are running against, it is useful
@@ -3197,8 +3173,7 @@ try(socket:send(result))
Suppose that you are convinced of the power of NSE. How do you
go about writing your own script? Let's say
that you want to extract information from an identification
server.
<indexterm><primary>auth service</primary></indexterm>
server.<indexterm><primary>auth service</primary></indexterm>
Nmap used to have this functionality but it was removed
because of inconsistencies in the code base. Fortunately, the
protocol identd uses is pretty simple. Unfortunately, it is too
@@ -3261,12 +3236,10 @@ port 113, queries the owner of the service on the scanned port and prints it."
backslash (&lsquo;<literal>\</literal>&rsquo;). They must also decide what
categories the script belongs to. This script is a good
example of a script which cannot be categorized clearly. It is
<literal>safe</literal>
<indexterm><primary><literal>safe</literal> script category</primary></indexterm>
<literal>safe</literal><indexterm><primary><literal>safe</literal> script category</primary></indexterm>
because we are not using the service
for anything it was not intended for. On the other hand, it
is <literal>intrusive</literal>
<indexterm><primary><literal>intrusive</literal> script category</primary></indexterm>
is <literal>intrusive</literal><indexterm><primary><literal>intrusive</literal> script category</primary></indexterm>
because we connect to a
service on the target and therefore potentially give out
information about us. To solve this dilemma we will place our
@@ -3357,8 +3330,7 @@ end
<literal>send()</literal> or
<literal>receive()</literal> we can operate on the network
socket. To avoid excessive error checking code we use NSE's
exception handling mechanism.
<indexterm><primary>exceptions in NSE</primary></indexterm>
exception handling mechanism.<indexterm><primary>exceptions in NSE</primary></indexterm>
We create a function which will
be executed if an error occurs and call this function
<literal>catch</literal>. Using this function we generate
@@ -3444,8 +3416,7 @@ end
true nature. NSE has been integrated into Nmap's version
detection framework to handle these cases. The scripts which
extend the version scanner belong to the reserved category
<literal>version</literal>.
<indexterm><primary><varname>version</varname> script category</primary></indexterm>
<literal>version</literal>.<indexterm><primary><varname>version</varname> script category</primary></indexterm>
This category cannot be run from
the command line. It is only executed if the user has required a
version scan. The following listing shows a simple script which
@@ -3469,7 +3440,7 @@ license = "Same as Nmap--See http://nmap.org/book/man-legal.html"<indexterm><pri
id = "HTTP version"<indexterm><primary><varname>id</varname> script variable</primary></indexterm>
categories = {"version"}<indexterm><primary><varname>categories</varname> script variable</primary></indexterm><indexterm><primary><varname>version</varname> script category</primary></indexterm>
categories = {"version"}<indexterm><primary><varname>categories</varname> script variable</primary></indexterm>
runlevel = 1.0<indexterm><primary><varname>runlevel</varname> script variable</primary></indexterm>
@@ -3856,18 +3827,15 @@ also get stored inside the registry.
<para>
The next phase of NSE initialization is loading the chosen
scripts, which are the arguments provided to the
<option>--script</option>
<indexterm><primary><option>--script</option></primary></indexterm>
<option>--script</option><indexterm><primary><option>--script</option></primary></indexterm>
option or <literal>default</literal>, in
case of a default script scan. The string <literal>version</literal>
<indexterm><primary><varname>version</varname> script category</primary></indexterm>
case of a default script scan. The string
<literal>version</literal><indexterm><primary><varname>version</varname> script category</primary></indexterm>
is appended, if version detection was enabled.
The arguments afterwards are tried to be
interpreted as script categories. This is done via a Lua C function
in <filename>nse_init.cc</filename> called <literal>entry</literal>.
Inside <filename>script.db</filename>,
<indexterm><primary><filename>script.db</filename></primary></indexterm>
<indexterm><primary><filename>script.db</filename></primary><seealso><option>--script-updatedb</option></seealso></indexterm>
Inside <filename>script.db</filename>,<indexterm><primary><filename>script.db</filename></primary><seealso><option>--script-updatedb</option></seealso></indexterm>
for each category of a script,
there is a call to <literal>Entry</literal>. If the category was chosen
then the script is loaded. Every argument of
@@ -3890,18 +3858,16 @@ also get stored inside the registry.
<sect2 id="nse-implementation-match">
<title>Matching of Scripts to Targets</title>
<para>
After the initialization is finished the <literal>hostrules</literal>
<indexterm><primary><varname>hostrule</varname> script variable</primary></indexterm>
and <literal>portrules</literal>
<indexterm><primary><varname>portrule</varname> script variable</primary></indexterm>
After the initialization is finished the
<literal>hostrules</literal><indexterm><primary><varname>hostrule</varname> script variable</primary></indexterm>
and <literal>portrules</literal><indexterm><primary><varname>portrule</varname> script variable</primary></indexterm>
are evaluated for each host in the current
target group. At this check a list is built which contains the combinations of scripts and the hosts they will run against.
It should be noted that the rules of all chosen scripts are
checked against all hosts and their <literal>open</literal>
<indexterm><primary><literal>open</literal> port state</primary></indexterm>
and <literal>open|filtered</literal>
<indexterm><primary><literal>open|filtered</literal> port state</primary></indexterm>
checked against all hosts and their
<literal>open</literal><indexterm><primary><literal>open</literal> port state</primary></indexterm>
and <literal>open|filtered</literal><indexterm><primary><literal>open|filtered</literal> port state</primary></indexterm>
ports.
Therefore it is advisable to leave the rules as simple as possible and
to do all the computation inside the <literal>action</literal>, as a script will only be
@@ -3921,8 +3887,8 @@ The mainloop function will work on each runlevel grouping of threads in order.
<title>Running Scripts</title>
<para>
Nmap is able to perform NSE script scanning in parallel
<indexterm><primary>parallelism</primary><secondary>in NSE</secondary></indexterm>
Nmap is able to perform NSE script scanning in
parallel<indexterm><primary>parallelism</primary><secondary>in NSE</secondary></indexterm>
by making use of Lua language features. In particular,
<ulink url="http://www.lua.org/manual/5.1/manual.html#2.11">coroutines
</ulink> offer collaborative multi-threading so scripts can suspend themselves at defined points, and allow other coroutines
@@ -3961,8 +3927,7 @@ The mainloop function will work on each runlevel grouping of threads in order.
functions they provide to Lua, which have to be of type <ulink url="http://www.lua.org/manual/5.1/manual.html#lua_CFunction">lua_CFunction</ulink>. Additionally they have to contain a function
which is used to actually open the module. By convention these function names are <literal>luaopen_<replaceable>modulename</replaceable></literal>.
A good starting point for writing such modules is provided by
<filename>bit.c</filename>
<indexterm><primary><varname>bit</varname> NSE module</primary></indexterm>
<filename>bit.c</filename><indexterm><primary><varname>bit</varname> NSE module</primary></indexterm>
inside
the <filename>nselib/</filename> subdirectory of Nmap's source tree.
<varname>bit</varname> is a C module already provided by the nselib. C modules
@@ -3992,8 +3957,7 @@ The mainloop function will work on each runlevel grouping of threads in order.
itself. Linking with static libraries
(e.g. <literal>libnbase</literal>) sometimes leads to
problems with exporting symbols on some platforms (in our
case the x86_64-linux platform).
<indexterm><primary>x86_64 architecture</primary></indexterm>
case the x86_64-linux platform).<indexterm><primary>x86_64 architecture</primary></indexterm>
To our knowledge no such
problems occur when linking against already existing shared
libraries.</para>