summaryrefslogtreecommitdiff
path: root/pkg/README
blob: a2e6ac5392ae06ea5170e6c10f83114d1e8eeda9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
$OpenBSD: README,v 1.24 2019/06/11 06:01:20 landry Exp $

+-----------------------------------------------------------------------
| Running ${PKGSTEM} 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.
firefox -ProfileManager, and click "Create Profile".

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

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 three
process types (main, content, 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.

Files containing pledge promises and unveil paths and permissions
for each type of process are located in
${LOCALBASE}/lib/${MOZILLA_PROJECT}/browser/defaults/preferences/.
Each file can be overridden by copying it to ${SYSCONFDIR}/firefox/
and modifying it.

3rd-Party MIME Handlers
=======================
Due to unveil(2) limiting filesystem access, only the default MIME
handler registered for a given type can be chosen when opening a
downloaded file.  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

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

	$ xdg-mime query default application/pdf

The older mailcap-format handlers are also supported, but the path
being executed must be explicitly added to the unveil.main file
with "rx" permissions.  For example, a ~/.mailcap file specifying:

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

must have "${LOCALBASE}/bin/xpdf rx" added to unveil.main for it to
appear as an option in the "Open With" drop-down.

Using mailto: links
===================
To enable mailto: links in Firefox to open in 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 build the debug FLAVOR of
this package, and run firefox inside egdb, so that you can gather
debugging logs and traces (for all threads!).

If this is a pledge violation, you should figure 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
/etc/${MOZILLA_PROJECT}/{unveil,pledge}.{main,content,gpu} to contain
just "disable".

D-BUS
=====
For proper integration with various desktop-oriented components, firefox
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.
Without a session bus running, the port is faking one (see
https://bugzilla.mozilla.org/show_bug.cgi?id=1466593), but GLIB might still try
to spawn one which might lead to a 'proc' pledge violation in the content
process.

HTML5 audio/video support
=========================
For a full multimedia experience, such as playing MP3 audio or MPEG
videos, install the "ffmpeg" package. It will be used at runtime if
firefox finds it.

# pkg_add ffmpeg

WebRTC support
==============
For WebRTC to properly work, it is required to enable audio recording:

# sysctl kern.audio.record=1

It is also required to change the ownership of the video(4) device so that your
regular user can access the webcam device.

# chown youruser /dev/video0

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 on unices the 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, for the rust-based WebRender compositor, it is enabled by setting
MOZ_WEBRENDER=1 in the environment, or by switching the about:config
gfx.webrender.enabled knob to true. Check it is enabled in the 'Features'
section of about:support. For this feature, WebGL2 is necessary, so your
hardware must support at least OpenGL 4.

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