firefox-esr-153.5.0

This README contains unresolved ports variables; replace them before using its commands.

+-----------------------------------------------------------------------
| Running firefox-esr on OpenBSD
+-----------------------------------------------------------------------

If you encounter strange problems relating to bookmarks, downloads,
window placement, toolbars, history, or other settings, it is
recommended that you create a new profile and attempt to
reproduce the problem before filing bugs.  To create a new profile,
start Firefox with the -ProfileManager switch, e.g.
${MOZILLA_PROJECT} -ProfileManager, and click "Create Profile".

If Firefox doesn't start at all, try starting it with the -safe-mode
switch, which temporarily disables extensions and themes.

pledge(2) and unveil(2) Support
===============================
Firefox on OpenBSD is secured with pledge(2) and unveil(2) to limit
the system calls and filesystem access that each of Firefox's process types
(main, content, remote data decoder, audio decoder, socket and GPU) is
permitted.  By default, only ~/Downloads and /tmp can be written to when
downloading files, or when viewing local files as file:// URLs.  You can edit
the following files to change the pledge promises, unveil paths, and associated
permissions:

${SYSCONFDIR}/${MOZILLA_PROJECT}/{unveil,pledge}.{content,gpu,main,rdd,socket,utility}

As unveil() can't show non-existing dirs, it is recommended to manually
create ~/Downloads for files to be properly saved in this directory.

Starting ${MOZILLA_PROJECT} should create this directory, but it won't be available
for downloads until it's restarted.

3rd-Party MIME Handlers
=======================
Due to unveil(2) limiting filesystem access, special care has to be
taken to unveil MIME handlers. For example, to use the mupdf package
to read PDFs, it must be registered as the default with XDG:

$ xdg-mime default mupdf.desktop application/pdf

And the corresponding binary must be unveiled for it to appear as an
option in the "Open With" drop-down for example adding the following
line to ${SYSCONFDIR}/${MOZILLA_PROJECT}/unveil.main:

${LOCALBASE}/bin/mupdf rx

The current default for a given type can be viewed with xdg-mime's
query command:

$ xdg-mime query default application/pdf

Alternatively, you can use mailcap, for example a ~/.mailcap file of:

application/pdf; ${LOCALBASE}/bin/xpdf %s

As with the XDG approach, the application(s) will need to be included in
${SYSCONFDIR}/${MOZILLA_PROJECT}/unveil.main.

Using mailto: links
===================
In order for mailto: links in Firefox to open your mail program,
you may have to set a mailto protocol handler. Type "about:config"
in Firefox's URL text field.  Type "mailto" in the filter.  If there
is a string called "network.protocol-handler.app.mailto", its value
names the application for mailto URLs. If present, right click,
choose Modify, and enter the path to your mail program, e.g.,
"${LOCALBASE}/bin/thunderbird" or "${LOCALBASE}/bin/kmail" (other
programs may work, but these two have been tested).  If absent,
right click, choose New String. Set the name to
"network.protocol-handler.app.mailto" and the value to the path to
your mailer.

Debugging
=========
If you encounter crashes, you might want to install the debug-${MOZILLA_PROJECT}
package, and run ${MOZILLA_PROJECT} inside egdb, so that you can gather debugging
logs and traces (for all threads!).

If this is a pledge violation, please try to find out which codepath
in which process leads to calling a forbidden syscall, and which pledge
is missing from the sets configured according to the section above.
Setting MOZ_LOG=OpenBSDSandbox:5 should help.  Bug reports without
enough information will be ignored.

To disable pledge and/or unveil support when troubleshooting, set the
corresponding pledge or unveil file in
${SYSCONFDIR}/${MOZILLA_PROJECT}/{unveil,pledge}.{main,content,gpu} to contain
just "disable".

D-BUS
=====
For proper integration with various desktop-oriented components, ${MOZILLA_PROJECT}
needs a session bus instance running.
If you're not running a desktop environment that takes care of it,
refer to /usr/local/share/doc/pkg-readmes/dbus to configure your
session startup script to start one.
If a session bus is not running, this port fakes the existence of one
(see https://bugzilla.mozilla.org/show_bug.cgi?id=1466593). However,
GLIB can still try to spawn a session bus which can then lead to a 'proc'
pledge violation in the content process.

WebRTC support
==============
For WebRTC to work properly, you need to enable audio and video recording:

# sysctl kern.audio.record=1
# sysctl kern.video.record=1

You will also need to change the ownership and/or permissions of the
relevant video(4) device so that your user can access the webcam
device e.g.:

# chown youruser /dev/video?

Screen sharing needs shmget() which isn't available when pledge() is active, so
you will have to disable pledge for the main process.

KerberosV support
=================
To use Kerberized Firefox, first manually install the "heimdal" package
and configure the Kerberos client.

Firefox will load the libraries at runtime if required. On OpenBSD, they
are installed in a non-standard location; to allow Firefox to find them,
either set LD_LIBRARY_PATH=${LOCALBASE}/heimdal/lib in your environment
(possibly via a shell alias or wrapper script if you only want to
set this for Firefox), or modify 'shlib_dirs' in /etc/rc.conf.local.

To instruct Firefox to use Kerberos for specific domains, open
'about:config' and modify the following key:

network.negotiate-auth.trusted-uris: .example.com

Graphic Acceleration
====================
By default, OpenGL acceleration is disabled.  One can enable it by
setting MOZ_ACCELERATED=1 in the environment, or by switching the about:config
layers.acceleration.force-enable knob to true.  Check the 'Decision log'
section in about:support to see whether HW_COMPOSITING and OPENGL_COMPOSITING
are enabled.

Similarly, the rust-based WebRender compositor can be enabled by setting
MOZ_WEBRENDER=1 in the environment, or by switching the about:config
gfx.webrender.enabled knob to true. Check that it's enabled in the 'Features'
section of about:support. For this feature, WebGL2 is necessary, so your
hardware must support at least OpenGL 4.

See https://wiki.mozilla.org/Platform/GFX/Quantum_Render for more details.

Fonts in PDF viewer
===================
If using the builtin PDF viewer and you get garbled fonts, bitmap fonts
should be rejected to fix rendering. A known workaround:

# ln -s /etc/fonts/conf.avail/70-no-bitmaps.conf /etc/fonts/conf.d