path: root/doc/guide/files/faq.xml

<!-- $NetBSD: faq.xml,v 1.49 2013/12/24 15:29:44 tron Exp $ -->

<chapter id="faq"> <?dbhtml filename="faq.html"?>
<title>Frequently Asked Questions</title>

<para>This section contains hints, tips &amp; tricks on special things in
pkgsrc that we didn't find a better place for in the previous chapters, and
it contains items for both pkgsrc users and developers.</para>

<!-- ================================================================== -->

  <sect1 id="mailing-list-pointers">
    <title>Are there any mailing lists for pkg-related discussion?</title>

    <para>The following mailing lists may be of interest to pkgsrc users:</para>

    <itemizedlist>

      <listitem>
	<para><ulink
	    url="http://www.NetBSD.org/mailinglists/index.html#pkgsrc-users">pkgsrc-users</ulink>:
	  This is a general purpose list for most issues regarding
	  pkgsrc, regardless of platform, e.g. soliciting user help
	  for pkgsrc configuration, unexpected build failures, using
	  particular packages, upgrading pkgsrc installations,
	  questions regarding the pkgsrc release branches, etc.  General announcements or
	  proposals for changes that impact the pkgsrc user community,
	  e.g. major infrastructure changes, new features, package
	  removals, etc., may also be posted.</para>
      </listitem>

      <listitem>
	<para><ulink
	    url="http://www.NetBSD.org/mailinglists/index.html#pkgsrc-bulk">pkgsrc-bulk</ulink>:
	  A list where the results of pkgsrc bulk builds are sent and
	  discussed.</para>
      </listitem>

      <listitem>
	<para><ulink
	    url="http://www.NetBSD.org/mailinglists/index.html#pkgsrc-changes">pkgsrc-changes</ulink>:
	  This list is for those who are interested in getting a
	  commit message for every change committed to pkgsrc. It is
	  also available in digest form, meaning one daily message
	  containing all commit messages for changes to the package
	  source tree in that 24 hour period.</para>
      </listitem>

    </itemizedlist>

<para>To subscribe, do:</para>

<programlisting>
&cprompt; echo subscribe <replaceable>listname</replaceable> | mail majordomo@NetBSD.org
</programlisting>

<para>Archives for all these mailing lists are available from
<ulink url="http://mail-index.NetBSD.org/"/>.</para>

</sect1>

<!-- ================================================================== -->

<sect1 id="pkgviews-docs">
<title>Where's the pkgviews documentation?</title>

<para>Pkgviews is tightly integrated with buildlink.  You can find a
pkgviews User's guide in
<filename>pkgsrc/mk/buildlink3/PKGVIEWS_UG</filename>.</para>

</sect1>

<!-- ================================================================== -->

<sect1 id="faq-pkgtools">
<title>Utilities for package management (pkgtools)</title>

<para>The directory <filename>pkgsrc/pkgtools</filename> contains
a number of useful utilities for both users and developers of pkgsrc.  This
section attempts only to make the reader aware of the utilities and when
they might be useful, and not to duplicate the documentation that comes
with each package.</para>

<para>Utilities used by pkgsrc (automatically installed when needed):</para>

<itemizedlist>

  <listitem>
    <para><filename role="pkg">pkgtools/x11-links</filename>:
      Symlinks for use by buildlink.</para>
  </listitem>

</itemizedlist>

<para>OS tool augmentation (automatically installed when needed):</para>

<itemizedlist>

  <listitem>
    <para><filename role="pkg">pkgtools/digest</filename>:
      Calculates various kinds of checksums (including SHA1).</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/libnbcompat</filename>:
      Compatibility library for pkgsrc tools.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/mtree</filename>: Installed on
      non-BSD systems due to lack of native mtree.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/pkg_install</filename>:
      Up-to-date replacement for
      <filename>/usr/sbin/pkg_install</filename>, or for use on operating
      systems where pkg_install is not present.</para>
  </listitem>

</itemizedlist>

<para>Utilities used by pkgsrc (not automatically installed):</para>

<itemizedlist>

  <listitem>
    <para><filename role="pkg">pkgtools/pkg_tarup</filename>:
      Create a binary package from an
      already-installed package.  Used by <command>make replace</command> to
      save the old package.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/dfdisk</filename>:
      Adds extra functionality to pkgsrc, allowing it to fetch distfiles
      from multiple locations. It currently supports the following
      methods: multiple CD-ROMs and network FTP/HTTP connections.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/xpkgwedge</filename>: Put X11
      packages someplace else (enabled by default).</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">devel/cpuflags</filename>: Determine
      the best compiler flags to optimise code for your current
      CPU and compiler. </para>
  </listitem>

</itemizedlist>

<para>Utilities for keeping track of installed packages, being up to date,
etc:</para>

<itemizedlist>

  <listitem>
    <para><filename role="pkg">pkgtools/pkg_chk</filename>: Reports on
      packages whose installed versions do not match the latest pkgsrc
      entries.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/pkgdep</filename>: Makes
      dependency graphs of packages, to aid in choosing a strategy for
      updating.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/pkgdepgraph</filename>: Makes
      graphs from the output of <filename
        role="pkg">pkgtools/pkgdep</filename> (uses graphviz).</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/pkglint</filename>: The
      pkglint(1) program checks a pkgsrc entry for errors.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/lintpkgsrc</filename>: The lintpkgsrc(1) program
      does various checks on the complete pkgsrc system.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/pkgsurvey</filename>: Report what
      packages you have installed.</para>
  </listitem>

</itemizedlist>

<para>Utilities for people maintaining or creating individual packages:</para>

<itemizedlist>

  <listitem>
    <para><filename role="pkg">pkgtools/pkgdiff</filename>: Automate
      making and maintaining patches for a package (includes pkgdiff,
      pkgvi, mkpatches, etc.).</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/rpm2pkg</filename>,
      <filename role="pkg">pkgtools/url2pkg</filename>: Aids in
      converting to pkgsrc.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/gensolpkg</filename>: Convert
      pkgsrc to a Solaris package.</para>
  </listitem>

</itemizedlist>

<para>Utilities for people maintaining pkgsrc (or: more obscure pkg
utilities)</para>

<itemizedlist>

  <listitem>
    <para><filename role="pkg">pkgtools/pkg_comp</filename>: Build
      packages in a chrooted area.</para>
  </listitem>

  <listitem>
    <para><filename role="pkg">pkgtools/libkver</filename>: Spoof
      kernel version for chrooted cross builds.</para>
  </listitem>

</itemizedlist>

</sect1>

<!-- ================================================================== -->

<sect1 id="non-root-pkgsrc">
<title>How to use pkgsrc as non-root</title>

<para>If you want to use pkgsrc as non-root user, you can set some
variables to make pkgsrc work under these conditions.  At the very least,
you need to set <varname>UNPRIVILEGED</varname> to <quote>yes</quote>; this
will turn on unprivileged mode and set multiple related variables to allow
installation of packages as non-root.</para>

<para>In case the defaults are not enough, you may want to tune some other
variables used.  For example, if the automatic user/group detection leads
to incorrect values (or not the ones you would like to use), you can change
them by setting <varname>UNPRIVILEGED_USER</varname> and
<varname>UNPRIVILEGED_GROUP</varname> respectively.</para>

<para>As regards bootstrapping, please note that the
<command>bootstrap</command> script will ease non-root configuration when
given the <quote>--ignore-user-check</quote> flag, as it will choose and
use multiple default directories under <filename>~/pkg</filename> as the
installation targets.  These directories can be overridden by the
<quote>--prefix</quote> flag provided by the script, as well as some others
that allow finer tuning of the tree layout.</para>

</sect1>

<!-- ================================================================== -->

<sect1 id="resume-transfers">
<title>How to resume transfers when fetching distfiles?</title>

<para>By default, resuming transfers in pkgsrc is disabled, but you can
enable this feature by adding the option
<varname>PKG_RESUME_TRANSFERS=YES</varname> into
&mk.conf;.  If, during a fetch step, an incomplete
distfile is found, pkgsrc will try to resume it.</para>

<para>You can also
use a different program than the platform default program by changing the
<varname>FETCH_USING</varname> variable.  You can specify the program by
using of ftp, fetch, wget or curl.  Alternatively, fetching can be disabled
by using the value manual.  A value of custom disables the system defaults
and dependency tracking for the fetch program.  In that case you have to
provide <varname>FETCH_CMD</varname>, <varname>FETCH_BEFORE_ARGS</varname>,
<varname>FETCH_RESUME_ARGS</varname>, <varname>FETCH_OUTPUT_ARGS</varname>,
<varname>FETCH_AFTER_ARGS</varname>.</para>

<para>For example, if you want to use
<filename>wget</filename> to download, you'll have to use something
like:</para>

<programlisting>
FETCH_USING=	wget
</programlisting>

</sect1>

<!-- ================================================================== -->

<sect1 id="x.org-from-pkgsrc">
<title>How can I install/use modular X.org from pkgsrc?</title>

<para>If you want to use modular X.org from pkgsrc instead of your system's own X11
(<filename>/usr/X11R6</filename>, <filename>/usr/openwin</filename>, ...)
you will have to add the following line into
&mk.conf;:</para>

<programlisting>
X11_TYPE=modular
</programlisting>

<note><para>The DragonFly operating system defaults to using modular X.org from pkgsrc.
</para></note>

</sect1>

<!-- ================================================================== -->

<sect1 id="fetch-behind-firewall">
<title>How to fetch files from behind a firewall</title>

<para>If you are sitting behind a firewall which does not allow direct
connections to Internet hosts (i.e. non-NAT), you may specify the
relevant proxy hosts.  This is done using an environment variable in the
form of a URL, e.g. in Amdahl, the machine
<quote>orpheus.amdahl.com</quote> is one of the firewalls, and it uses
port 80 as the proxy port number.  So the proxy environment variables
are:</para>

<programlisting>
ftp_proxy=ftp://orpheus.amdahl.com:80/
http_proxy=http://orpheus.amdahl.com:80/
</programlisting>

</sect1>

<!-- ================================================================== -->

<sect1 id="passive-ftp">
<title>How do I tell <command>make fetch</command> to do passive FTP?</title>

<para>This depends on which utility is used to retrieve distfiles.  From
<filename>bsd.pkg.mk</filename>, <varname>FETCH_CMD</varname> is assigned
the first available command from the following list:</para>

<itemizedlist>
  <listitem>
    <para><filename>${LOCALBASE}/bin/ftp</filename></para>
  </listitem>
  <listitem>
    <para><filename>/usr/bin/ftp</filename></para>
  </listitem>
</itemizedlist>

<para>On a default NetBSD installation, this will be
<filename>/usr/bin/ftp</filename>, which automatically tries passive
connections first, and falls back to active connections if the server
refuses to do passive.  For the other tools, add the following to your
&mk.conf; file:
<varname>PASSIVE_FETCH=1</varname>.</para>

<para>Having that option present will prevent
<filename>/usr/bin/ftp</filename> from falling back to active
transfers.</para>

</sect1>

<!-- ================================================================== -->

<sect1 id="fetching-all-distfiles">
<title>How to fetch all distfiles at once</title>

<para>You would like to download all the distfiles in a single batch
from work or university, where you can't run a <command>make
fetch</command>.  There is an archive of distfiles on <ulink
url="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/">ftp.NetBSD.org</ulink>,
but downloading the entire directory may not be appropriate.</para>

<para>The answer here is to do a <command>make fetch-list</command> in
<filename>/usr/pkgsrc</filename> or one of its subdirectories, carry the
resulting list to your machine at work/school and use it there.  If you
don't have a NetBSD-compatible &man.ftp.1; (like tnftp) at work, don't
forget to set <varname>FETCH_CMD</varname> to something that fetches a
URL:</para>

<para>At home:</para>

<screen>&cprompt; <userinput>cd /usr/pkgsrc</userinput>
&cprompt; <userinput>make fetch-list FETCH_CMD=wget DISTDIR=/tmp/distfiles >/tmp/fetch.sh</userinput>
&cprompt; <userinput>scp /tmp/fetch.sh work:/tmp</userinput></screen>

<para>At work:</para>

<screen>&cprompt; <userinput>sh /tmp/fetch.sh</userinput></screen>

<para>then tar up <filename>/tmp/distfiles</filename> and take it
home.</para>

<para>If you have a machine running NetBSD, and you want to get
<emphasis>all</emphasis> distfiles (even ones that aren't for your
machine architecture), you can do so by using the above-mentioned
<command>make fetch-list</command> approach, or fetch the distfiles
directly by running:</para>

<screen>&cprompt; <userinput>make mirror-distfiles</userinput></screen>

<para>If you even decide to ignore
<varname>NO_{SRC,BIN}_ON_{FTP,CDROM}</varname>, then you can get everything
by running:</para>

<screen>&cprompt; <userinput>make fetch NO_SKIP=yes</userinput></screen>

</sect1>

<!-- ================================================================== -->

<sect1 id="tmac.andoc-missing">
<title>What does <quote>Don't know how to make
/usr/share/tmac/tmac.andoc</quote> mean?</title>

<para>When compiling the <filename role="pkg">pkgtools/pkg_install</filename>
package, you get the error from make that it doesn't know how to make
<filename>/usr/share/tmac/tmac.andoc</filename>? This indicates that
you don't have installed the <quote>text</quote> set (nroff, ...) from
the NetBSD base distribution on your machine.  It is recommended to do
that to format man pages.</para>

<para>In the case of the <filename
  role="pkg">pkgtools/pkg_install</filename> package, you
can get away with setting <varname>NOMAN=YES</varname> either in the
environment or in &mk.conf;.</para>

</sect1>

<!-- ================================================================== -->

<sect1 id="bsd.own.mk-missing">
<title>What does <quote>Could not find bsd.own.mk</quote> mean?</title>

<para>You didn't install the compiler set, <filename>comp.tgz</filename>,
when you installed your NetBSD machine.  Please get and install it, by
extracting it in <filename>/</filename>:</para>

<screen>&rprompt; <userinput>cd /</userinput>
&rprompt; <userinput>tar --unlink -zxvpf .../comp.tgz</userinput></screen>

<para><filename>comp.tgz</filename> is part of every NetBSD release.  Get
the one that corresponds to your release (determine via <command>uname
-r</command>).</para>

</sect1>

<!-- ================================================================== -->

<sect1 id="using-sudo-with-pkgsrc">
<title>Using 'sudo' with pkgsrc</title>

<para>When installing packages as non-root user and using the just-in-time
&man.su.1; feature of pkgsrc, it can become annoying to type in the root
password for each required package installed.  To avoid this, the sudo
package can be used, which does password caching over a limited time.  To
use it, install sudo (either as binary package or from
<filename role="pkg">security/sudo</filename>) and then put the
following into your &mk.conf;, somewhere
<emphasis>after</emphasis> the definition of the
<varname>LOCALBASE</varname> variable:</para>

<programlisting>
.if exists(${LOCALBASE}/bin/sudo)
SU_CMD=        ${LOCALBASE}/bin/sudo /bin/sh -c
.endif
</programlisting>

</sect1>

<!-- ================================================================== -->

<sect1 id="faq.conf">
<title>How do I change the location of configuration files?</title>

<para>As the system administrator, you can choose where configuration files
are installed.  The default settings make all these files go into
<filename>${PREFIX}/etc</filename> or some of its subdirectories; this may
be suboptimal depending on your expectations (e.g., a read-only,
NFS-exported <varname>PREFIX</varname> with a need of per-machine
configuration of the provided packages).</para>

<para>In order to change the defaults, you can modify the
<varname>PKG_SYSCONFBASE</varname> variable (in
&mk.conf;) to point to your preferred configuration
directory; some common examples include <filename>/etc</filename> or
<filename>/etc/pkg</filename>.</para>

<para>Furthermore, you can change this value on a per-package basis by
setting the <varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname> variable.
<varname>PKG_SYSCONFVAR</varname>'s value usually matches the name of the
package you would like to modify, that is, the contents of
<varname>PKGBASE</varname>.</para>

<para>Note that after changing these settings, you must rebuild and
reinstall any affected packages.</para>

</sect1>

<!-- ================================================================== -->

<sect1 id="audit-packages">
<title>Automated security checks</title>

<para>Please be aware that there can often be bugs in third-party software,
and some of these bugs can leave a machine vulnerable to exploitation by
attackers.  In an effort to lessen the exposure, the NetBSD packages team
maintains a database of known-exploits to packages which have at one time
been included in pkgsrc.  The database can be downloaded automatically, and
a security audit of all packages installed on a system can take place.  To
do this, refer to the following two tools (installed as part of the
<filename role="pkg">pkgtools/pkg_install</filename> package):</para>

<orderedlist>

  <listitem>
    <para><command>pkg_admin fetch-pkg-vulnerabilities</command>, an easy way to
    download a list of the security vulnerabilities information.  This list
    is kept up to date by the pkgsrc security team, and is distributed
    from the NetBSD ftp server:</para>

    <para><ulink
    url="ftp://ftp.NetBSD.org/pkgsrc/distfiles/pkg-vulnerabilities"/></para>
  </listitem>

  <listitem>
    <para><command>pkg_admin audit</command>, an easy way to audit the
    current machine, checking each known vulnerability.  If a
    vulnerable package is installed, it will be shown by output to stdout,
    including a description of the type of vulnerability, and a URL
    containing more information.</para>
  </listitem>

</orderedlist>

<para>Use of these tools is strongly recommended!  After
<quote>pkg_install</quote> is installed, please read
the package's message, which you can get by running <userinput>pkg_info -D
pkg_install</userinput>.</para>

<para>If this package is installed, pkgsrc builds will use it to
perform a security check before building any package.  See <xref
linkend="variables-affecting-build"/> for ways to control this
check.</para>

</sect1>

<sect1 id="ufaq-cflags">
<title>Why do some packages ignore my <varname>CFLAGS</varname>?</title>

	<para>When you add your own preferences to the
	<varname>CFLAGS</varname> variable in your
	&mk.conf;, these flags are passed in
	environment variables to the <filename>./configure</filename>
	scripts and to &man.make.1;. Some package authors ignore the
	<varname>CFLAGS</varname> from the environment variable by
	overriding them in the <filename>Makefile</filename>s of their
	package.</para>

	<para>Currently there is no solution to this problem. If you
	really need the package to use your <varname>CFLAGS</varname>
	you should run <command>make patch</command> in the package
	directory and then inspect any <filename>Makefile</filename> and
	<filename>Makefile.in</filename> for whether they define
	<varname>CFLAGS</varname> explicitly. Usually you can remove
	these lines. But be aware that some <quote>smart</quote>
	programmers write so bad code that it only works for the
	specific combination of <varname>CFLAGS</varname> they have
	chosen.</para>

</sect1>

<sect1 id="ufaq-fail">
<title>A package does not build.  What shall I do?</title>

	<procedure>

	<step><para>Make sure that your copy of pkgsrc is consistent. A
	case that occurs often is that people only update pkgsrc in
	parts, because of performance reasons. Since pkgsrc is one large
	system, not a collection of many small systems, there are
	sometimes changes that only work when the whole pkgsrc tree is
	updated.</para></step>

	<step><para>Make sure that you don't have any CVS conflicts.
	Search for <quote>&lt;&lt;&lt;&lt;&lt;&lt;</quote> or
	<quote>&gt;&gt;&gt;&gt;&gt;&gt;</quote> in all your pkgsrc
	files.</para></step>

	<step><para>Make sure that you don't have old copies of the packages
	extracted. Run <command>make clean clean-depends</command> to
	verify this.</para></step>

	<step><para>If the problem still exists, write a mail to the
	<literal>pkgsrc-users</literal> mailing list.</para></step>

	</procedure>
</sect1>

<sect1 id="faq.rcs-conflicts">
<title>What does <quote>Makefile appears to contain unresolved cvs/rcs/??? merge conflicts</quote> mean?</title>

<para>You have modified a file from pkgsrc, and someone else has
modified that same file afterwards in the CVS repository. Both changes
are in the same region of the file, so when you updated pkgsrc, the
<literal>cvs</literal> command marked the conflicting changes in the
file. Because of these markers, the file is no longer a valid
<filename>Makefile</filename>.</para>

<para>Have a look at that file, and if you don't need your local changes
anymore, you can remove that file and run <command>cvs -q update
-dP</command> in that directory to download the current version.</para>

</sect1>
</chapter>