https://wiki.archlinux.org/api.php?action=feedcontributions&user=Ondrian&feedformat=atomArchWiki - User contributions [en]2024-03-29T02:22:24ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=MATLAB&diff=800059MATLAB2024-02-09T10:41:09Z<p>Ondrian: Fix typo</p>
<hr />
<div>[[Category:Numerical analysis]]<br />
[[ja:MATLAB]]<br />
[[zh-hans:MATLAB]]<br />
{{Related articles start}}<br />
{{Related|Octave}}<br />
{{Related|Sage-mathematics}}<br />
{{Related|Mathematica}}<br />
{{Related articles end}}<br />
{{Style|unnecessarily verbose, sometimes written in in first person}}<br />
From the [https://www.mathworks.com/products/matlab.html official website]:<br />
<br />
:MATLAB is a programming and numeric computing platform used by millions of engineers and scientists to analyze data, develop algorithms, and create models.<br />
<br />
== Overview ==<br />
<br />
MATLAB is proprietary software produced by The MathWorks and requires a license to obtain, install, and activate. New versions of MATLAB are released twice a year,<br />
release names are composed of {{ic|R}}, the year of the release and {{ic|a}} or {{ic|b}}.<br />
Arch Linux is not officially supported.<br />
[https://www.mathworks.com/support/requirements/matlab-linux.html]<br />
<br />
== Installation ==<br />
<br />
A complete copy of the MATLAB software must be obtained before it can be installed. The MATLAB software is available to licenses holders on both a DVD and through the [https://www.mathworks.com MathWorks website]. In addition to the software a file installation key is required for installation. It is possible to install MATLAB either with the {{AUR|matlab}} package or from the MATLAB installation software directly. The advantage of the {{AUR|matlab}} package is that it manages dependencies and some of the nuances of the installation process while installing directly from the MATLAB installation software can be done by regular users to their home directories.<br />
<br />
=== Installing from the MATLAB installation software ===<br />
<br />
The MATLAB installation software is self contained and does not require any additional packages to install in silent mode. To install with the GUI a working [[Xorg]] graphical display is necessary. [[Wayland]] is not officially supported yet, so it will run in a Xwayland session. The installation is handled by the {{ic|install}} script. You can run the script as root to install MATLAB system-wide or your user to install it only for you.<br />
<br />
During the installation, you are asked if you want symlinks to be created. If you did not choose to do so, you can now manually create a symlink in {{ic|/usr/local/bin}} to make it easier to launch in terminal:<br />
<br />
# ln -s /{MATLAB}/bin/matlab /usr/local/bin<br />
<br />
Or you could add MATLAB install path to {{ic|PATH}} environment variable.<br />
<br />
{{Note|If the installation crashes with {{ic|Failed to launch web window with error: Unable to launch the MATLABWindow application.}}, see [[#Unable to launch the MATLABWindow application]] for a workaround.}}<br />
<br />
=== Installing with MATLAB Package Manager (MPM) ===<br />
<br />
[https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md MATLAB Package Manager] (MPM) offers a streamlined method to install MATLAB and accompanying MathWorks products on Linux systems, directly from the command line. This utility facilitates programmatic installation without necessitating user sign-in, a File Installation Key, or a pre-acquired license file, deferring activation and licensing to post-installation. MPM permits specification of MATLAB release version, additional toolboxes, and installation directory. Additionally, it serves well for constructing MATLAB Docker containers. As of 2023, the MATLAB installer does not support Wayland, and this is an easy way to install MATLAB via command-line.<br />
<br />
Here's how to acquire MPM and set it up for execution (ensure wget is installed):<br />
<br />
{{hc|wget https://www.mathworks.com/mpm/glnxa64/mpm|chmod +x mpm}}<br />
<br />
Installation of MATLAB and desired products is conducted with the following syntax:<br />
<br />
./mpm install --release=<release> --destination=<destination> [--products] <product1> <product2> [...]<br />
<br />
For instance, to install MATLAB R2021b along with select toolboxes to a specified directory, the command would be:<br />
<br />
./mpm install --release=R2021b --destination=/home/username/matlab MATLAB Simulink Deep_Learning_Toolbox Parallel_Computing_Toolbox<br />
<br />
The full list of correctly formatted product names can be found within the [https://github.com/mathworks-ref-arch/matlab-dockerfile/tree/main/mpm-input-files template input files].<br />
<br />
==== Desktop entry ====<br />
<br />
Optionally create a [[desktop entry]]. The MIME type of MATLAB files is {{ic|text/x-matlab}}.<br />
<br />
Start {{ic|matlab}} with:<br />
<br />
* {{ic|-desktop}} to run Matlab without a terminal.<br />
* {{ic|-nosplash}} to prevent the splash screen from showing up.<br />
<br />
In order for icons to appear correctly {{ic|StartupWMClass}} needs to be set in the desktop entry. To find it out start MATLAB, run {{ic|xprop {{!}} grep WM_CLASS}} and select the MATLAB window.<br />
<br />
Example desktop entry: <br />
<br />
{{hc|/usr/share/applications/matlab.desktop|2=<br />
[Desktop Entry]<br />
Type=Application<br />
Terminal=false<br />
MimeType=text/x-matlab<br />
Exec=/usr/local/MATLAB/R20''xyz''/bin/matlab -desktop<br />
Name=MATLAB<br />
Icon=matlab<br />
Categories=Development;Math;Science<br />
Comment=Scientific computing environment<br />
StartupNotify=true<br />
}}<br />
<br />
If one need to set environment variable, one could prepend {{ic|env}} in {{ic|Exec}}, for example, to system's libfreetype:<br />
<br />
Exec=env LD_PRELOAD=/usr/lib/libfreetype.so.6 matlab<br />
<br />
One might want to use the system's {{ic|libstdc++}}.<br />
<br />
=== Installing from the AUR package ===<br />
<br />
The {{AUR|matlab}} package is designed to allow MATLAB to be integrated into and managed by Arch. Note however, that the package does not contain the installation files, and you are expected to place them in the cloned package folder yourself. It can be problematic to build the package using [[AUR helpers]], so you are expected to do so manually. You can obtain the actual MATLAB software using the installer from [https://www.mathworks.com the MathWorks website].<br />
<br />
{{Warning|The EULA for the proprietary MATLAB software is restrictive and it prohibits distribution and modification of the installation files. The installation method described in this section should only be performed on the system on which the software is going to be installed and the package should be deleted from the installation location and the [[pacman]] cache following installation. Redistributing the built package is a violation of the MATLAB EULA.}}<br />
<br />
* Clone the {{AUR|matlab}} package and {{ic|cd}} into it.<br />
* Download the zip file containing the MATLAB installer from MathWorks into the current directory. Extract the zip to the {{ic|matlab}} subdirectory:<br />
$ bsdtar xC matlab -f matlab_''XXXXX''_glnxa64.zip<br />
* Run the extracted installer with:<br />
$ ./matlab/install<br />
* The installer gives you a choice of either installing the software now or only downloading selected modules. Choose the second option. This option may also be under the "Advanced Options" dropdown menu.<br />
* The installer will give you an option to change the download path. You might want to change it to something temporary (like {{ic|/tmp}} if you have big enough ram disk) as you will soon move the contents to a different location.<br />
* Wait for the download to finish and close the installer. Merge the downloaded archives into the extracted {{ic|matlab}} subdirectory:<br />
$ rsync -a /selected/download/folder/''YYYY_MM_DD_HH_MM_SS''/ matlab<br />
* Then package the directory into a tarball:<br />
$ tar -cvf matlab.tar matlab<br />
* Download your licence:Go to [https://mathworks.com/mwaccount/ your MathWorks account] and click on the licence number you want to use. Then, go to the ''Install and activate'' tab and select ''Activate to retrieve licence File''. Follow the instructions and download the licence file needed for the installation. Name the file {{ic|matlab.lic}} and place it in the AUR package directory. There will also be a File Installation Key (FIK) visible on the MathWorks website. Copy-paste it in a new file named {{ic|matlab.fik}} and save it next to {{ic|PKGBUILD}} just like you did with the {{ic|matlab.lic}}.<br />
* Now, you will create a pacman package. You can customize the modules you want the package to contain by modifying the {{ic|PKGBUILD}} or leave it at default:<br />
{{hc|PKGBUILD|2=<br />
...<br />
# Limit products to lower size, set this to true to do a partial install<br />
partialinstall=false<br />
# Example list of products for a partial install; check README.md for details<br />
products=(<br />
"MATLAB"<br />
#---MATLAB Product Family---#<br />
"Curve_Fitting_Toolbox" # Math and Optimization<br />
"Database_Toolbox" # Database Access and Reporting<br />
"Deep_Learning_HDL_Toolbox"<br />
"Deep_Learning_Toolbox"<br />
"DSP_System_Toolbox"<br />
"Global_Optimization_Toolbox"<br />
"GPU_Coder"<br />
"MATLAB_Coder" # Code Generation<br />
"MATLAB_Compiler" # Application Deployement<br />
"MATLAB_Compiler_SDK"<br />
"Optimization_Toolbox"<br />
"Parallel_Computing_Toolbox" # Parallel computing<br />
"Partial_Differential_Equation_Toolbox"<br />
"Reinforcement_Learning_Toolbox"<br />
"Statistics_and_Machine_Learning_Toolbox" # AI, Data Science, Statistics<br />
"Symbolic_Math_Toolbox"<br />
"Text_Analytics_Toolbox"<br />
#---Application Products---#<br />
"Audio_Toolbox"<br />
"Bioinformatics_Toolbox" # Computational Biology<br />
"Computer_Vision_Toolbox"<br />
"Image_Processing_Toolbox" # Image Processing and Computer Vision<br />
"Signal_Processing_Toolbox" # Signal Processing<br />
"Wavelet_Toolbox"<br />
)<br />
...<br />
}}<br />
* Finally, use {{ic|makepkg}} command to build and install the package:<br />
$ makepkg -sri<br />
<br />
== Configuration ==<br />
<br />
=== Java ===<br />
<br />
The MATLAB software is bundled with a JVM and therefore it is not necessary to install [[Java]]. The JVM version supported by MATLAB is listed in [https://ww2.mathworks.cn/support/compilers.html System Requirements & Platform Availability] or simply type {{ic|version -java}} in MATLAB. One could set the {{ic|MATLAB_JAVA}} environment variable to use custom JVM, for example, to specify the {{pkg|jre8-openjdk}} JRE, launch MATLAB with:<br />
<br />
$ env MATLAB_JAVA=/usr/lib/jvm/java-8-openjdk/jre matlab<br />
<br />
=== OpenGL acceleration ===<br />
<br />
MATLAB can take advantage of hardware based 2D and 3D OpenGL acceleration. Support for hardware acceleration needs to be configured outside of MATLAB. Appropriate [[video drivers]] need to be installed along with the OpenGL utility library {{Pkg|glu}} package. If X11 forwarding is being used, the video drivers need to be installed on both the client and server. To check if MATLAB is making use of hardware based OpenGL acceleration run:<br />
<br />
$ matlab -nodesktop -nosplash -r "opengl info; exit" | grep Software<br />
<br />
If "software rendering" is not "false", then there is a problem with your hardware acceleration. If this is the case make sure OpenGL is configured correctly on the system. This can be done with the {{ic|glxinfo}} program from the {{Pkg|mesa-utils}} package:<br />
<br />
$ glxinfo | grep "direct rendering"<br />
<br />
If "direct rendering" is not "yes", then there is likely a problem with your system configuration.<br />
<br />
If glxinfo works but not matlab, you can try to run:<br />
<br />
$ export LD_PRELOAD=/usr/lib/libstdc++.so; export LD_LIBRARY_PATH=/usr/lib/xorg/modules/dri/; matlab -nodesktop -nosplash -r "opengl info; exit" | grep Software<br />
<br />
If it works, you can edit Matlab launcher script to add:<br />
<br />
export LD_PRELOAD=/usr/lib/libstdc++.so<br />
export LD_LIBRARY_PATH=/usr/lib/dri/<br />
<br />
After these changes, you may see low-level graphics errors in the MATLAB console such as:<br />
<br />
com.jogamp.opengl.GLException: X11GLXDrawableFactory - Could not initialize shared resources for X11GraphicsDevice[type .x11, connection :0, unitID 0, handle 0x0, owner false, ResourceToolkitLock[obj 0x76ddc7cd, isOwner false, <6876ff80, 5d5c50dc>[count 0, qsz 0, owner <NULL>]]]<br />
at jogamp.opengl.x11.glx.X11GLXDrawableFactory$SharedResourceImplementation.createSharedResource(X11GLXDrawableFactory.java:326)<br />
at jogamp.opengl.SharedResourceRunner.run(SharedResourceRunner.java:297)<br />
at java.lang.Thread.run(Thread.java:748)<br />
Caused by: java.lang.NullPointerException<br />
at jogamp.opengl.GLContextImpl.makeCurrent(GLContextImpl.java:688)<br />
at jogamp.opengl.GLContextImpl.makeCurrent(GLContextImpl.java:580)<br />
at jogamp.opengl.x11.glx.X11GLXDrawableFactory$SharedResourceImplementation.createSharedResource(X11GLXDrawableFactory.java:297)<br />
... 2 more<br />
<br />
In that case, create a file with the name 'java.opts' in the directory where MATLAB is executed (for example {{ic|/usr/local/MATLAB/R2020a/bin/glnxa64}}) with the following line:<br />
<br />
{{hc|java.opts|2=<br />
-Djogl.disable.openglarbcontext=1<br />
}}<br />
<br />
=== Sound ===<br />
<br />
To confirm that MATLAB is able to use the default soundcard to present sounds run:<br />
<br />
$ matlab -nodesktop -nosplash -r "load handel; sound(y, Fs); pause(length(y)/Fs); exit" > /dev/null<br />
<br />
This should play an except from Handel's "Hallelujah Chorus." If this fails make sure [[ALSA]] is properly configured. This can be done with the {{ic|speaker-test}} program from the {{Pkg|alsa-utils}} package:<br />
<br />
$ speaker-test<br />
<br />
If you do not hear anything, then there is likely a problem with your system configuration.<br />
<br />
=== GPU computing ===<br />
<br />
MATLAB can take advantage of [https://www.mathworks.co.uk/discovery/matlab-gpu.html CUDA enabled GPUs] to speed up applications. In order to take advantage of a supported GPU install the {{Pkg|nvidia}}, {{Pkg|nvidia-utils}}, {{Pkg|ocl-icd}}, {{Pkg|opencl-nvidia}}, and {{Pkg|cuda}} packages. To check if MATLAB is able to utilize the GPU run:<br />
<br />
$ matlab -nodesktop -nosplash -r "x=rand(10, 'single'); g=gpuArray(x); Success=isequal(gather(g), x), exit" | sed -ne '/Success =/,$p'<br />
<br />
=== Install supported compilers ===<br />
<br />
In order to access the full functionality of MATLAB (e.g., to use Simulink, Builder JA, and MEX-file compilation), supported versions of the {{ic|gcc}}, {{ic|g++}}, {{ic|gfortran}}, and {{ic|jdk}} compilers must be installed. Details about the supported compilers for the [https://www.mathworks.com/support/compilers.html current release] and [https://www.mathworks.com/support/sysreq/previous_releases.html previous releases] are available online. Many of the supported {{ic|gcc}}, {{ic|g++}}, {{ic|jdk}} compiler versions for past MATLAB releases are available from the [[AUR]] (e.g., {{AUR|gcc43}}, {{AUR|gcc44}}, {{AUR|gcc47}}, {{AUR|gcc49}}and {{AUR|jdk7}}), while past versions of the {{ic|gfortran}} compilers are not packaged.<br />
<br />
To use previous versions of the {{ic|gcc}}, {{ic|g++}}, and {{ic|gfortran}} compilers with MEX files, edit {{ic|${MATLAB}/bin/mexopts.sh}} and replace all occurrences of {{ic|<nowiki>CC='gcc'</nowiki>}} with {{ic|<nowiki>CC='gcc-4.X'</nowiki>}}, {{ic|<nowiki>CXX='g++'</nowiki>}} with {{ic|<nowiki>CXX='g++-4.X'</nowiki>}}, and {{ic|<nowiki>FC='gfortran'</nowiki>}} with {{ic|<nowiki>FC='gfortran-4.X'</nowiki>}}, where {{ic|X}} is the compiler version appropriate for the particular MATLAB release.<br />
<br />
{{Note|<br />
* Newer versions of Matlab (at least 2017a) does not seem to respect the {{ic|${MATLAB}/bin/mexopts.sh}} customization. Instead it uses {{ic|${MATLAB}/bin/glnxa64/mexopts/LANG_glnxa64.xml}} file.<br />
* Though, it is not officially supported, one could still use higher version of compiler, and ignore the warnings.<br />
}}<br />
<br />
=== Help browser ===<br />
<br />
The help browser uses valuable slots in the dynamic thread vector and causes competition with core functionality provided by libraries like the BLAS that also depend on the dynamic thread vector. The help browser can be configured to use fewer slots in the dynamic thread vector with<br />
<br />
>> webutils.htmlrenderer('basic');<br />
<br />
This is a persistent change and to reverse it use<br />
<br />
>> webutils.htmlrenderer('default');<br />
<br />
=== Serial port access ===<br />
<br />
To successfully connect to any serial port, MATLAB expects to have write access directly to {{ic|/var/lock}} which is not allowed on Arch Linux for security reasons. Instead of allowing this access just for MATLAB, you can work around this problem by redirecting device locking using {{AUR|lockdev-redirect}}. All you have to do is executing MATLAB like this:<br />
<br />
# lockdev-redirect /{MATLAB}/bin/matlab<br />
<br />
If you have created a .desktop file as shortcut to MATLAB, then add "lockdev-redirect" as a prefix to your "Exec=" entry.<br />
<br />
=== HiDPI and 4k ===<br />
<br />
See [[HiDPI#MATLAB]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Warning: Initializing MATLAB Graphics failed ===<br />
<br />
This error seems to happen on multi-monitor setups, see [https://www.mathworks.com/matlabcentral/answers/611786-warning-initializing-matlab-graphics-failed#comment_1131148 this forum post].<br />
<br />
=== Blackscreen in help browser and livescripts ===<br />
<br />
In order to use help browser and livescripts install {{aur|libselinux}}.<br />
<br />
=== Static TLS errors ===<br />
<br />
MATLAB has a number of libraries that have been compiled with static thread local storage (TLS) including the help browser {{ic|doc}} and the BLAS libraries. For example,<br />
<br />
>> doc('help');<br />
>> ones(10)*randn(10);<br />
Error using * <br />
BLAS loading error:<br />
dlopen: cannot load any more object with static TLS<br />
<br />
is related to the bugs:<br />
<br />
* [https://www.mathworks.de/support/bugreports/961964 961964] for which patched libraries are available from [http://www.mathworks.de/support/bugreports/license/accept_license/5730?fname=attachment_961964_12b_13a_13b_14a_glnxa64_2014-01-30.zip&geck_id=961964 MathWorks]{{Dead link|2020|03|30|status=404}}<br />
* [https://www.mathworks.com/support/bugreports/1003952 1003952] for which workarounds exist<br />
<br />
A more general solution of recompiling {{ic|glibc}} has also been suggested. [https://stackoverflow.com/a/19468365]<br />
<br />
=== Blank/grey UI when using WM (non-reparenting window manager) ===<br />
<br />
See [[Java#Gray window, applications not resizing with WM, menus immediately closing]].<br />
<br />
=== Corrupted text and fonts in menus and fields ===<br />
<br />
If you notice that the menus or the input fields are corrupted or not appearing correctly then you can try to activate the ''"'''Use antialiasing to smooth desktop fonts'''"'' option in Matlab preferences, it seems to solve the problem. Go to '''''Preferences -> Matlab -> Fonts''''' and activate it. You will need to restart Matlab in order to take affect.<br />
<br />
=== Installation dependencies missing ===<br />
<br />
Matlab might complain that it cannot find a package. Look at the package name and install it with [[Pacman]], or in the case of x86_64 there are some libraries only in [[AUR]]. {{AUR|matlab}} and {{AUR|matlab-dummy}} packages contain a list of up-to-date dependencies for the newest Matlab version.<br />
<br />
See also [[#Unable to launch the MATLABWindow application]].<br />
<br />
=== Installation error: archive is not a ZIP archive ===<br />
<br />
During the installation you can get:<br />
<br />
The following error was detected while installing ''package_name'': archive is not a ZIP archive <br />
Would you like to retry installing ''package_name''? If you press No, the installer will exit without completing the installation. More information can be found at /tmp/mathworks_root.log<br />
<br />
Matlab downloads all packages to {{ic|/tmp/}} directory which resides in RAM and is maximum size of half of available memory. In this case it is not enough for installation files and Matlab 2019a installer will warn you about this. If it did not, or if you ignored the warning, you will have got the above error.<br />
<br />
You can either [[Tmpfs#Examples|resize tmpfs]] (3,5 GB is not enough, 6 GB works), or remove packages from base install and add them later with built-in Matlab add-on installer.<br />
<br />
=== Install-time library errors ===<br />
<br />
* Make sure that the symlink {{ic|bin/glnx64/libstdc++.so.6}} is pointing to the correct version of {{ic|libstdc++.so.xx}} (which is also in the same directory and has numbers where 'xx' is). By default, it may be pointing to an older (and nonexistent) version (different value for 'xx').<br />
<br />
* Make sure the device you are installing from is not mounted as {{ic|noexec}}<br />
<br />
* If you downloaded the files from Mathworks' website, make sure they are not on an NTFS or FAT partition, because that can mess up the symlinks. Ext4 or Ext3 should work.<br />
<br />
=== Hangs on rendering or exiting with Intel graphics ===<br />
<br />
Some users have reported issues with DRI3 enabled on Intel Graphics chips. A possible workaround is to disable DRI3 and run MATLAB with hardware rendering on DRI2; to do so, launch MATLAB with the environment variable LIBGL_DRI3_DISABLE set to 1:<br />
<br />
LIBGL_DRI3_DISABLE=1 /{MATLAB}/bin/matlab<br />
<br />
If the previous workaround does not work, the issue can be circumvented by selecting software rendering with the MATLAB command (beware, performance may be very poor when doing e.g. big or complex 3D plots):<br />
<br />
opengl('save','software')<br />
<br />
See [https://bugzilla.redhat.com/show_bug.cgi?id=1357571] and [https://bugs.freedesktop.org/show_bug.cgi?id=96671] for more.<br />
<br />
=== LiveScript errors ===<br />
<br />
If you get the error when attempting to load or create a LiveScript:<br />
{{ic|Viewing matlab live script files is not currently supported by this operating system configuration}}<br />
*It could be because of broken symlinks of {{Pkg|libgcrypt}} and other dependencies, after system updates. On the first start of the Live Editor the components are extracted and these libary symlinks are created (if not existing).<br />
: A solution is to simply delete the whole folder containing the broken symlinks and the extracted components, which are in the installation directory:<br />
''matlab_root''/sys/jxbrowser-chromium<br />
: Or, if the installation directory is not user writable, then in:<br />
~/.matlab/R2017b/HtmlPanel<br />
: Matlab will then regenerate the contents on the next Live Editor start.<br />
: A better option is to replace libgcrypt symlink in this extraction directory with a less precise one. For example, after extraction, this link to /lib64/libgcrypt.so.20.2.4 is created. Replace it with e.g. /lib64/libgcrypt.so.20.<br />
: Matlab R2020 does not contain a chromium directory anymore. Relinking the library file libcrypto.so.1.1 with the system file can resolve the issue. It is located in:<br />
''matlab_root''/bin/glnxa64<br />
*Also the steps in [[#Unable to launch the MATLABWindow application]] may resolve the issue.<br />
*It can also happen due to missing gconf package. Make sure {{AUR|gconf}} is installed.<br />
*If the above does not help, execute in the command window<br />
>> com.mathworks.mde.liveeditor.widget.rtc.CachedLightweightBrowserFactory.createLightweightBrowser()<br />
to get a more detailed error message.<br />
* A debugging console can be opened with<br />
>> com.mathworks.mde.webbrowser.HtmlPanelDebugConsole.invoke;<br />
<br />
=== Using webcam/video device ===<br />
<br />
Make sure the correct support package add-ons are installed (webcam or OS Generic Video Interface for example). If running matlab as a user, make sure your user has write permissions to wherever the support packages are being downloaded and installed.<br />
<br />
Since MATLAB R2017a, Image Acqusition Toolbox is using GStreamer library version 1.0. It previously used version 0.10.<br />
<br />
In general, USB Webcam Support Package does a better job working with UVC and built-in cameras than OS Generic Video Interface Support Package.<br />
<br />
=== MATLAB hangs for several minutes when closing Help Browser ===<br />
<br />
{{Style|Written in first person}}<br />
<br />
Since upgrade of glibc from 2.24 to 2.25, MATLAB (at least R2017a) hangs when closing Help Browser. The issue is related to the particular version of jxbrowser-chromium shipped with MATLAB.<br />
This issue is still present with glibc 2.26 and MATLAB R2017b and R2018a.<br />
<br />
To fix this issue, download the [https://www.teamdev.com/jxbrowser latest jxbrowser] and replace the following jars from MATLAB:<br />
<br />
''matlab_root''/java/jarext/jxbrowser-chromium/jxbrowser-chromium.jar<br />
''matlab_root''/java/jarext/jxbrowser-chromium/jxbrowser-linux64.jar<br />
<br />
MATLAB should automatically unpack those jars into {{ic|''matlab_root''/sys/jxbrowser-chromium/glnxa64/chromium}} when first opening Help Browser.<br />
Remove {{ic|''matlab_root''/sys/jxbrowser-chromium/glnxa64/chromium}} directory to make sure MATLAB uses the latest jxbrowser.<br />
<br />
Unfortunately, this workaround does not work in R2017b anymore. Going deeper into investigation of this issue, it is related to a crash of one of jxbrowser-chromium processes. The parent process of jxbrowser-chromium then sits there and waits for response from a process that is already dead. This causes MATLAB main window to freeze. You can easily unfreeze MATLAB by manually killing all leftover jxbrowser-chromium processes.<br />
<br />
I have come up with this simple script that uses inotify and waits for user to close Help browser in MATLAB. It triggers when user closes Help browser and sends kill signal to all leftover jxbrowser-chromium processes:<br />
<br />
{{bc|1=<br />
#!/bin/sh<br />
<br />
if [ -z "$1" ]; then<br />
REL=R2017b<br />
else<br />
REL=$1<br />
fi<br />
<br />
JXPATH="/path/to/MATLAB/$REL/sys/jxbrowser-chromium/glnxa64/chromium"<br />
CMD="inotifywait -m -e CLOSE $JXPATH/resources.pak"<br />
<br />
#Exit if the daemon is already active<br />
if ! pgrep -f "$CMD" > /dev/null; then<br />
#Wait for user to close Help Browser, then killall leftover jxbrowser processes<br />
$CMD {{!}}<br />
while read line<br />
do<br />
killall "$JXPATH/jxbrowser-chromium"<br />
done<br />
else<br />
exit<br />
fi<br />
}}<br />
<br />
I run this script as part of my MATLAB start script like that:<br />
~/bin/unfreeze_matlab.sh R2017b &<br />
<br />
To make sure that this background job is killed when I exit MATLAB, I use this in the beginning of MATLAB start script:<br />
trap "trap - SIGTERM && kill -- -$$" SIGINT SIGTERM EXIT<br />
<br />
=== Some dropdown menus cannot be selected ===<br />
<br />
In some interfaces - such as Simulation Data Inspector or Simulink Test Manager - nothing happens when choosing an item in dropdown menu (for example, when trying to change a number of subplots in Simulation Data Inspector). To work around this issue, hold down the Shift key while clicking the item in dropdown menu.<br />
<br />
=== Not starting - licensing error ===<br />
<br />
In case MATLAB will not start from a [[desktop environment]] by the call of its [[desktop file]] one should see the output as you start it from the terminal.<br />
<br />
For a ''Licensing error'' such as:<br />
<br />
{{hc|# matlab|<nowiki><br />
MATLAB is selecting SOFTWARE OPENGL rendering.<br />
License checkout failed.<br />
License Manager Error -9<br />
This error may occur when: <br />
-The hostid of this computer does not match the hostid in the license file. <br />
-A Designated Computer installation is in use by another user. <br />
If no other user is currently running MATLAB, you may need to activate.<br />
<br />
Troubleshoot this issue by visiting: <br />
https://www.mathworks.com/support/lme/R2017a/9<br />
<br />
Diagnostic Information:<br />
Feature: MATLAB <br />
License path: /home/<USER>/.matlab/R2017a_licenses/license_<NUM>_R2017a.lic:/home/<USER>/.matlab/R2017a_licenses/lice<br />
nse_Darkness_<NUM>_R2017a.lic:/opt/MATLAB/R2017a/licenses/license.dat:/opt/MATLAB/R2017a/licenses/*<br />
.lic <br />
Licensing error: -9,57.<br />
</nowiki>}}<br />
<br />
A re-activation might solve the problem.<br />
<br />
/usr/local/MATLAB/R2017a/bin/activate_matlab.sh -javadir /usr/lib/jvm/java-8-openjdk/jre/<br />
<br />
=== MATLAB crashes with "Failure loading desktop class" on startup ===<br />
<br />
In case MATLAB will not start and starting it from command line gives you the following error:<br />
{{hc<br />
|$ matlab|<br />
Fatal Internal Error: Internal Error: Failure occurs during desktop startup. Details: Failure loading desktop class.<br />
}}<br />
and you have the option [[Java#GTK LookAndFeel|-Dswing.defaultlaf=com.sun.java.swing.plaf.gtk.GTKLookAndFeel]] set in your {{ic|_JAVA_OPTIONS}} environment variable, start MATLAB with<br />
<br />
$ _JAVA_OPTIONS= matlab<br />
<br />
If this works, add the line<br />
<br />
export _JAVA_OPTIONS=<br />
<br />
to your MATLAB launcher script. Optionally re-add other Java options.<br />
<br />
=== Unable to type in text fields of interfaces based on MATLABWindow ===<br />
<br />
{{Style|Written in first person}}<br />
Since R2018a, it is not possible to type text in interfaces based on MATLABWindow - like Signal Editor, Add-Ons Explorer and others.<br />
MATLABWindow and MATLAB's webwindow infrastructure is based on Chromium Embedded Framework, and it looks like a known and long standing bug: https://bitbucket.org/chromiumembedded/cef/issues/2026/multiple-major-keyboard-focus-issues-on<br />
<br />
One possible workaround is to switch focus from the MATLABWindow to another window and then switch back - so that you can type.<br />
<br />
To elaborate more on this workaround (since the problem is still there in R2018b), here is what i did in my Openbox config (note that the A-Middle keybinding already exist in default config):<br />
<br />
<mousebind button="A-Middle" action="Press"><br />
<action name="Unfocus"/><br />
<action name="Focus"/><br />
</mousebind><br />
<br />
Now, whenever it is not possible to type in a text field, I press Alt+Mouse middle mouse and then I can type again.<br />
<br />
This problem is critical during installation. After one clicks some elements in the installation window, he will not be able to type into any textbox anymore and switching between windows does not always work. To circumvent the issue, one shall only use key-press, instead of mouse click during installation. MATLAB installer has a poor support on Wayland, one may also consider using other WM instead during installation.<br />
<br />
=== Unable to launch the MATLABWindow application ===<br />
<br />
In MATLAB versions R2018b until R2022b, the installer crashes as follows:<br />
<br />
{{hc<br />
| $ ./install |<br />
terminate called after throwing an instance of 'std::runtime_error'<br />
what(): Failed to launch web window with error: Unable to launch the MATLABWindow application. The exit code was: 127<br />
[1] 1409378 IOT instruction (core dumped) ./install<br />
}}<br />
<br />
To find out why {{ic|MATLABWindow}} is crashing, run it manually to get detailed information.<br />
<br />
{{hc<br />
| $ ./bin/glnxa64/MATLABWindow |<br />
bin/glnxa64/MATLABWindow: symbol lookup error: /usr/lib/libcairo.so.2: undefined symbol: FT_Get_Color_Glyph_Layer<br />
}}<br />
<br />
{{ic|FT_Get_Color_Glyph_Layer}} is a symbol of {{Pkg|freetype2}}, which indicates a library incompatibility between the MATLAB application and the Arch Linux packages. [https://ww2.mathworks.cn/matlabcentral/answers/364551-why-is-matlab-unable-to-run-the-matlabwindow-application-on-linux]<br />
<br />
To fix this, put aside MATLAB's {{ic|libfreetype.so*}}.<br />
<br />
$ rm ./bin/glnxa64/libfreetype.so*<br />
<br />
You can also use {{ic|LD_PRELOAD}} environment variable to force MATLAB use Arch Linux's libfreetype without removing the lib file.<br />
<br />
$ export LD_PRELOAD=/lib64/libfreetype.so<br />
$ ./install<br />
<br />
Similarly, if the error is caused by {{ic|undefined symbol: g_log_structured...}}, put aside MATLAB's {{ic|libglib-2.0.so*}}. If the error is caused by {{ic|path to/libstdc++.so.6: version `CXXABI_1.3.9' not found (required by _somelibrary_)}}, put aside MATLAB's {{ic|libstdc++.so.6}}.<br />
<br />
=== Cannot verify university login during installation ===<br />
<br />
For total headcount license users, MATLAB will pop-up a window asking the user to login with their credentials in a web browser. However, if run with {{ic|sudo}}, most browsers (especially chromium) will not run. To circumvent this problem, one shall 'active the computer' through MATLAB's website using a browser by a normal user. [https://www.mathworks.com/matlabcentral/answers/326647-verify-university-login-not-open-browser See this issue]<br />
<br />
=== Missing libcrypt.so.1 ===<br />
<br />
If you get this error when launching or installing MATLAB (R2020a and later), install {{Pkg|libxcrypt-compat}}.<br />
<br />
=== Running installer as root does not launch the GUI ===<br />
<br />
If you run the installer as root and the GUI does not appear (but does appear without launching as root), try temporarily allowing the root user to access the X Server by running the following commands in order (where {{ic|./install}} is the command to run the installer as root):<br />
<br />
$ xhost +SI:localuser:root<br />
# ./install<br />
$ xhost -SI:localuser:root<br />
<br />
Note that the last command should be executed upon finishing the installation process, and {{ic|localuser}} is a string literal. See [https://au.mathworks.com/matlabcentral/answers/1461039-on-ubuntu-sudo-won-t-run-the-install-file#comment_1782671 this support answer], and {{man|1|xhost}}.<br />
<br />
In addition, verify that the {{ic|DISPLAY}} environment variable is set.<br />
<br />
An alternative is to install MATLAB as a local user.<br />
<br />
=== GUI installer is unable to create the target folder when installing as user ===<br />
<br />
Make the folder manually (as root), and take ownership. The path is typically /usr/local/MATLAB<br />
# mkdir -p /path/to/MATLAB/R20XXx<br />
# chown -R $LOGNAME: /path/to/MATLAB/R20XXx<br />
<br />
=== MATLAB crashes when opening Simulink ===<br />
<br />
When running from terminal the error message is:<br />
<br />
Inconsistency detected by ld.so: ../elf/dl-tls.c: 597: _dl_allocate_tls_init: Assertion `listp != NULL' failed!<br />
<br />
See upstream bug report here: https://www.mathworks.com/support/bugreports/details/2632298<br />
<br />
=== MATLAB cannot open or create script files ===<br />
<br />
See [[#Unable to launch the MATLABWindow application]].<br />
<br />
=== Calls to mex fail ===<br />
<br />
If calls from MATLAB or Simulink to mex (e.g. rapid accelerator) fail with the error {{ic|*.mexa64 is not a MEX file}}, even though the resulting file is usable, it may help to edit {{ic|}} in either {{ic|matlab/bin/}} or {{ic|~/.matlab7rc.sh}} by changing the {{ic|LDPATH_PREFIX}} variable from its empty default: [https://github.com/alecjacobson/matlab/blob/883d417a99fcb8ead89387cee243e51a92864019/bin/.matlab7rc.sh#L170]<br />
<br />
{{hc|matlab/bin/.matlab7rc.sh (or ~/.matlab7rc.sh)|2=<br />
...<br />
case "$ARCH" in<br />
'''glnx*)''' # Make sure you are modifying case '''glnx*'''<br />
AUTOMOUNT_MAP=<nowiki>''</nowiki><br />
DISPLAY="$DISPLAY"<br />
ARCH="$ARCH"<br />
TOOLBOX="$TOOLBOX"<br />
MATLABPATH="$MATLABPATH"<br />
SHELL="$SHELL"<br />
'''LDPATH_PREFIX='/usr/lib' '''<br />
...<br />
}}<br />
<br />
=== Incompatibilities with some python libraries using MKL ===<br />
<br />
Some python code running inside matlab may fail with an error mentioning {{ic|Parameter * was incorrect on entry to }}. This can be avoided by calling<br />
py.sys.setdlopenflags(int32(bitor(int64(py.os.RTLD_NOW), int64(py.os.RTLD_DEEPBIND))));<br />
or<br />
py.sys.setdlopenflags(int32(bitor(int64(py.os.RTLD_LAZY), int64(py.os.RTLD_DEEPBIND))));<br />
directly before any calls to {{ic|py}} and after calls to {{ic|pyenv}}.<br />
See [https://www.mathworks.com/matlabcentral/answers/358233-matlab-python-interface-broken?s_tid=email_ans_new_ans_ans_h#answer_283353 this support answer].<br />
<br />
=== Settings not persisting between MATLAB restarts ===<br />
<br />
In some cases on recent Arch systems matlab is unable to export {{ic|.mlsettings}} files, preventing toolbox and some matlab settings from being saved to disk and persisted. These cases come from matlab trying to hard link new files from {{ic|/tmp}} directly to the preferences directory (usually {{ic|~/.matlab/release}} where {{ic|release}} is the matlab version, e.g. {{ic|R2021b}}). As a workaround, run matlab with the {{ic|$TMPDIR}} environment variable set to a folder on the same file system as the preferences directory. [https://www.mathworks.com/matlabcentral/answers/1777865-matlab-preferences-not-being-saved-across-sessions]<br />
<br />
=== "Unable to open this file in the current system configuration" ===<br />
<br />
The error can be fixed by setting aside the l{{ic|ibfreetype.so.6}} in {{ic|''matlab_root''/bin/glnxa64/}}. You may run the following command:<br />
<br />
cd ''matlab_root''/bin/glnxa64/<br />
mv libfreetype.so.6 libfreetype.so.6.old<br />
<br />
=== Symbols in toolstrip menus are not diplayed properly ===<br />
<br />
{{Expansion|Explain which symbols are needed, so that users can choose any font providing them.}}<br />
<br />
This issue can be fixed by [[install]]ing {{Pkg|noto-fonts}}.<br />
<br />
=== Blank screen on Xwayland ===<br />
As suggested in [[Wayland#Java]], this issue can be fixed by adding in the Matlab launcher script:<br />
export _JAVA_AWT_WM_NONREPARENTING=1<br />
<br />
== MATLAB in a systemd-nspawn ==<br />
<br />
MATLAB can be run within a systemd-nspawn container to maintain a static system and avoid the library issues that often plague matlab installs after significant updates to libraries in Arch. Refer to [[Systemd-nspawn]] for detailed information on setting up such containers.<br />
<br />
The following instruction is to get a MATLAB R2021b installation running in a minimal Debian 11 environment. It assumes MATLAB is already installed as normal in "/usr/local/MATLAB/R2021b".<br />
<br />
Use [[Xhost]] to allow the nspawn environment to use the existing X server instance, see also [[Systemd-nspawn#Use an X environment]].<br />
<br />
Create a minimal Debian environment in a directory ("deb11" here) with:<br />
<br />
$ debootstrap --include=systemd-container --components=main,contrib bullseye deb11<br />
<br />
Set a password for the root user and create regular user:<br />
<br />
$ systemd-nspawn -D deb11<br />
passwd<br />
useradd -m username<br />
logout<br />
<br />
and then boot the environment with:<br />
<br />
$ systemd-nspawn --bind-ro=/dev/dri --bind-ro=/tmp/.X11-unix --bind=/dev/shm --bind=/usr/local/MATLAB --setenv=DISPLAY=:0 --setenv=MESA_LOADER_DRIVER_OVERRIDE=i965 -b -D deb11<br />
<br />
Install the following packages to have the required libraries in the nspawn environment for MATLAB: https://github.com/mathworks-ref-arch/container-images/blob/master/matlab-deps/r2021b/ubuntu20.04/Dockerfile<br />
<br />
"mesa-utils" and dependencies needs to be installed to support graphics acceleration.<br />
"usbutils" can be installed to support usb interfaces for I/O with MATLAB.<br />
<br />
Install the matlab-support (from contrib source) package in the environment for some convenient integration. <br />
<br />
$ apt-get install matlab-support<br />
<br />
MATLAB can be launched from within the environment normally by using the binary at {{ic|''matlab_root''/bin}}.<br />
<br />
Another way is to add something like <br />
-u username -a /usr/local/MATLAB/R2021b/bin/matlab -nosoftwareopengl -useStartupFolderPref<br />
<br />
to the systemd-nspawn command above.</div>Ondrianhttps://wiki.archlinux.org/index.php?title=MATLAB&diff=800058MATLAB2024-02-09T10:40:34Z<p>Ondrian: Added info about toolbox names.</p>
<hr />
<div>[[Category:Numerical analysis]]<br />
[[ja:MATLAB]]<br />
[[zh-hans:MATLAB]]<br />
{{Related articles start}}<br />
{{Related|Octave}}<br />
{{Related|Sage-mathematics}}<br />
{{Related|Mathematica}}<br />
{{Related articles end}}<br />
{{Style|unnecessarily verbose, sometimes written in in first person}}<br />
From the [https://www.mathworks.com/products/matlab.html official website]:<br />
<br />
:MATLAB is a programming and numeric computing platform used by millions of engineers and scientists to analyze data, develop algorithms, and create models.<br />
<br />
== Overview ==<br />
<br />
MATLAB is proprietary software produced by The MathWorks and requires a license to obtain, install, and activate. New versions of MATLAB are released twice a year,<br />
release names are composed of {{ic|R}}, the year of the release and {{ic|a}} or {{ic|b}}.<br />
Arch Linux is not officially supported.<br />
[https://www.mathworks.com/support/requirements/matlab-linux.html]<br />
<br />
== Installation ==<br />
<br />
A complete copy of the MATLAB software must be obtained before it can be installed. The MATLAB software is available to licenses holders on both a DVD and through the [https://www.mathworks.com MathWorks website]. In addition to the software a file installation key is required for installation. It is possible to install MATLAB either with the {{AUR|matlab}} package or from the MATLAB installation software directly. The advantage of the {{AUR|matlab}} package is that it manages dependencies and some of the nuances of the installation process while installing directly from the MATLAB installation software can be done by regular users to their home directories.<br />
<br />
=== Installing from the MATLAB installation software ===<br />
<br />
The MATLAB installation software is self contained and does not require any additional packages to install in silent mode. To install with the GUI a working [[Xorg]] graphical display is necessary. [[Wayland]] is not officially supported yet, so it will run in a Xwayland session. The installation is handled by the {{ic|install}} script. You can run the script as root to install MATLAB system-wide or your user to install it only for you.<br />
<br />
During the installation, you are asked if you want symlinks to be created. If you did not choose to do so, you can now manually create a symlink in {{ic|/usr/local/bin}} to make it easier to launch in terminal:<br />
<br />
# ln -s /{MATLAB}/bin/matlab /usr/local/bin<br />
<br />
Or you could add MATLAB install path to {{ic|PATH}} environment variable.<br />
<br />
{{Note|If the installation crashes with {{ic|Failed to launch web window with error: Unable to launch the MATLABWindow application.}}, see [[#Unable to launch the MATLABWindow application]] for a workaround.}}<br />
<br />
=== Installing with MATLAB Package Manager (MPM) ===<br />
<br />
[https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md MATLAB Package Manager] (MPM) offers a streamlined method to install MATLAB and accompanying MathWorks products on Linux systems, directly from the command line. This utility facilitates programmatic installation without necessitating user sign-in, a File Installation Key, or a pre-acquired license file, deferring activation and licensing to post-installation. MPM permits specification of MATLAB release version, additional toolboxes, and installation directory. Additionally, it serves well for constructing MATLAB Docker containers. As of 2023, the MATLAB installer does not support Wayland, and this is an easy way to install MATLAB via command-line.<br />
<br />
Here's how to acquire MPM and set it up for execution (ensure wget is installed):<br />
<br />
{{hc|wget https://www.mathworks.com/mpm/glnxa64/mpm|chmod +x mpm}}<br />
<br />
Installation of MATLAB and desired products is conducted with the following syntax:<br />
<br />
/mpm install --release=<release> --destination=<destination> [--products] <product1> <product2> [...]<br />
<br />
For instance, to install MATLAB R2021b along with select toolboxes to a specified directory, the command would be:<br />
<br />
mpm install --release=R2021b --destination=/home/username/matlab MATLAB Simulink Deep_Learning_Toolbox Parallel_Computing_Toolbox<br />
<br />
The full list of correctly formatted product names can be found within the [https://github.com/mathworks-ref-arch/matlab-dockerfile/tree/main/mpm-input-files template input files].<br />
<br />
==== Desktop entry ====<br />
<br />
Optionally create a [[desktop entry]]. The MIME type of MATLAB files is {{ic|text/x-matlab}}.<br />
<br />
Start {{ic|matlab}} with:<br />
<br />
* {{ic|-desktop}} to run Matlab without a terminal.<br />
* {{ic|-nosplash}} to prevent the splash screen from showing up.<br />
<br />
In order for icons to appear correctly {{ic|StartupWMClass}} needs to be set in the desktop entry. To find it out start MATLAB, run {{ic|xprop {{!}} grep WM_CLASS}} and select the MATLAB window.<br />
<br />
Example desktop entry: <br />
<br />
{{hc|/usr/share/applications/matlab.desktop|2=<br />
[Desktop Entry]<br />
Type=Application<br />
Terminal=false<br />
MimeType=text/x-matlab<br />
Exec=/usr/local/MATLAB/R20''xyz''/bin/matlab -desktop<br />
Name=MATLAB<br />
Icon=matlab<br />
Categories=Development;Math;Science<br />
Comment=Scientific computing environment<br />
StartupNotify=true<br />
}}<br />
<br />
If one need to set environment variable, one could prepend {{ic|env}} in {{ic|Exec}}, for example, to system's libfreetype:<br />
<br />
Exec=env LD_PRELOAD=/usr/lib/libfreetype.so.6 matlab<br />
<br />
One might want to use the system's {{ic|libstdc++}}.<br />
<br />
=== Installing from the AUR package ===<br />
<br />
The {{AUR|matlab}} package is designed to allow MATLAB to be integrated into and managed by Arch. Note however, that the package does not contain the installation files, and you are expected to place them in the cloned package folder yourself. It can be problematic to build the package using [[AUR helpers]], so you are expected to do so manually. You can obtain the actual MATLAB software using the installer from [https://www.mathworks.com the MathWorks website].<br />
<br />
{{Warning|The EULA for the proprietary MATLAB software is restrictive and it prohibits distribution and modification of the installation files. The installation method described in this section should only be performed on the system on which the software is going to be installed and the package should be deleted from the installation location and the [[pacman]] cache following installation. Redistributing the built package is a violation of the MATLAB EULA.}}<br />
<br />
* Clone the {{AUR|matlab}} package and {{ic|cd}} into it.<br />
* Download the zip file containing the MATLAB installer from MathWorks into the current directory. Extract the zip to the {{ic|matlab}} subdirectory:<br />
$ bsdtar xC matlab -f matlab_''XXXXX''_glnxa64.zip<br />
* Run the extracted installer with:<br />
$ ./matlab/install<br />
* The installer gives you a choice of either installing the software now or only downloading selected modules. Choose the second option. This option may also be under the "Advanced Options" dropdown menu.<br />
* The installer will give you an option to change the download path. You might want to change it to something temporary (like {{ic|/tmp}} if you have big enough ram disk) as you will soon move the contents to a different location.<br />
* Wait for the download to finish and close the installer. Merge the downloaded archives into the extracted {{ic|matlab}} subdirectory:<br />
$ rsync -a /selected/download/folder/''YYYY_MM_DD_HH_MM_SS''/ matlab<br />
* Then package the directory into a tarball:<br />
$ tar -cvf matlab.tar matlab<br />
* Download your licence:Go to [https://mathworks.com/mwaccount/ your MathWorks account] and click on the licence number you want to use. Then, go to the ''Install and activate'' tab and select ''Activate to retrieve licence File''. Follow the instructions and download the licence file needed for the installation. Name the file {{ic|matlab.lic}} and place it in the AUR package directory. There will also be a File Installation Key (FIK) visible on the MathWorks website. Copy-paste it in a new file named {{ic|matlab.fik}} and save it next to {{ic|PKGBUILD}} just like you did with the {{ic|matlab.lic}}.<br />
* Now, you will create a pacman package. You can customize the modules you want the package to contain by modifying the {{ic|PKGBUILD}} or leave it at default:<br />
{{hc|PKGBUILD|2=<br />
...<br />
# Limit products to lower size, set this to true to do a partial install<br />
partialinstall=false<br />
# Example list of products for a partial install; check README.md for details<br />
products=(<br />
"MATLAB"<br />
#---MATLAB Product Family---#<br />
"Curve_Fitting_Toolbox" # Math and Optimization<br />
"Database_Toolbox" # Database Access and Reporting<br />
"Deep_Learning_HDL_Toolbox"<br />
"Deep_Learning_Toolbox"<br />
"DSP_System_Toolbox"<br />
"Global_Optimization_Toolbox"<br />
"GPU_Coder"<br />
"MATLAB_Coder" # Code Generation<br />
"MATLAB_Compiler" # Application Deployement<br />
"MATLAB_Compiler_SDK"<br />
"Optimization_Toolbox"<br />
"Parallel_Computing_Toolbox" # Parallel computing<br />
"Partial_Differential_Equation_Toolbox"<br />
"Reinforcement_Learning_Toolbox"<br />
"Statistics_and_Machine_Learning_Toolbox" # AI, Data Science, Statistics<br />
"Symbolic_Math_Toolbox"<br />
"Text_Analytics_Toolbox"<br />
#---Application Products---#<br />
"Audio_Toolbox"<br />
"Bioinformatics_Toolbox" # Computational Biology<br />
"Computer_Vision_Toolbox"<br />
"Image_Processing_Toolbox" # Image Processing and Computer Vision<br />
"Signal_Processing_Toolbox" # Signal Processing<br />
"Wavelet_Toolbox"<br />
)<br />
...<br />
}}<br />
* Finally, use {{ic|makepkg}} command to build and install the package:<br />
$ makepkg -sri<br />
<br />
== Configuration ==<br />
<br />
=== Java ===<br />
<br />
The MATLAB software is bundled with a JVM and therefore it is not necessary to install [[Java]]. The JVM version supported by MATLAB is listed in [https://ww2.mathworks.cn/support/compilers.html System Requirements & Platform Availability] or simply type {{ic|version -java}} in MATLAB. One could set the {{ic|MATLAB_JAVA}} environment variable to use custom JVM, for example, to specify the {{pkg|jre8-openjdk}} JRE, launch MATLAB with:<br />
<br />
$ env MATLAB_JAVA=/usr/lib/jvm/java-8-openjdk/jre matlab<br />
<br />
=== OpenGL acceleration ===<br />
<br />
MATLAB can take advantage of hardware based 2D and 3D OpenGL acceleration. Support for hardware acceleration needs to be configured outside of MATLAB. Appropriate [[video drivers]] need to be installed along with the OpenGL utility library {{Pkg|glu}} package. If X11 forwarding is being used, the video drivers need to be installed on both the client and server. To check if MATLAB is making use of hardware based OpenGL acceleration run:<br />
<br />
$ matlab -nodesktop -nosplash -r "opengl info; exit" | grep Software<br />
<br />
If "software rendering" is not "false", then there is a problem with your hardware acceleration. If this is the case make sure OpenGL is configured correctly on the system. This can be done with the {{ic|glxinfo}} program from the {{Pkg|mesa-utils}} package:<br />
<br />
$ glxinfo | grep "direct rendering"<br />
<br />
If "direct rendering" is not "yes", then there is likely a problem with your system configuration.<br />
<br />
If glxinfo works but not matlab, you can try to run:<br />
<br />
$ export LD_PRELOAD=/usr/lib/libstdc++.so; export LD_LIBRARY_PATH=/usr/lib/xorg/modules/dri/; matlab -nodesktop -nosplash -r "opengl info; exit" | grep Software<br />
<br />
If it works, you can edit Matlab launcher script to add:<br />
<br />
export LD_PRELOAD=/usr/lib/libstdc++.so<br />
export LD_LIBRARY_PATH=/usr/lib/dri/<br />
<br />
After these changes, you may see low-level graphics errors in the MATLAB console such as:<br />
<br />
com.jogamp.opengl.GLException: X11GLXDrawableFactory - Could not initialize shared resources for X11GraphicsDevice[type .x11, connection :0, unitID 0, handle 0x0, owner false, ResourceToolkitLock[obj 0x76ddc7cd, isOwner false, <6876ff80, 5d5c50dc>[count 0, qsz 0, owner <NULL>]]]<br />
at jogamp.opengl.x11.glx.X11GLXDrawableFactory$SharedResourceImplementation.createSharedResource(X11GLXDrawableFactory.java:326)<br />
at jogamp.opengl.SharedResourceRunner.run(SharedResourceRunner.java:297)<br />
at java.lang.Thread.run(Thread.java:748)<br />
Caused by: java.lang.NullPointerException<br />
at jogamp.opengl.GLContextImpl.makeCurrent(GLContextImpl.java:688)<br />
at jogamp.opengl.GLContextImpl.makeCurrent(GLContextImpl.java:580)<br />
at jogamp.opengl.x11.glx.X11GLXDrawableFactory$SharedResourceImplementation.createSharedResource(X11GLXDrawableFactory.java:297)<br />
... 2 more<br />
<br />
In that case, create a file with the name 'java.opts' in the directory where MATLAB is executed (for example {{ic|/usr/local/MATLAB/R2020a/bin/glnxa64}}) with the following line:<br />
<br />
{{hc|java.opts|2=<br />
-Djogl.disable.openglarbcontext=1<br />
}}<br />
<br />
=== Sound ===<br />
<br />
To confirm that MATLAB is able to use the default soundcard to present sounds run:<br />
<br />
$ matlab -nodesktop -nosplash -r "load handel; sound(y, Fs); pause(length(y)/Fs); exit" > /dev/null<br />
<br />
This should play an except from Handel's "Hallelujah Chorus." If this fails make sure [[ALSA]] is properly configured. This can be done with the {{ic|speaker-test}} program from the {{Pkg|alsa-utils}} package:<br />
<br />
$ speaker-test<br />
<br />
If you do not hear anything, then there is likely a problem with your system configuration.<br />
<br />
=== GPU computing ===<br />
<br />
MATLAB can take advantage of [https://www.mathworks.co.uk/discovery/matlab-gpu.html CUDA enabled GPUs] to speed up applications. In order to take advantage of a supported GPU install the {{Pkg|nvidia}}, {{Pkg|nvidia-utils}}, {{Pkg|ocl-icd}}, {{Pkg|opencl-nvidia}}, and {{Pkg|cuda}} packages. To check if MATLAB is able to utilize the GPU run:<br />
<br />
$ matlab -nodesktop -nosplash -r "x=rand(10, 'single'); g=gpuArray(x); Success=isequal(gather(g), x), exit" | sed -ne '/Success =/,$p'<br />
<br />
=== Install supported compilers ===<br />
<br />
In order to access the full functionality of MATLAB (e.g., to use Simulink, Builder JA, and MEX-file compilation), supported versions of the {{ic|gcc}}, {{ic|g++}}, {{ic|gfortran}}, and {{ic|jdk}} compilers must be installed. Details about the supported compilers for the [https://www.mathworks.com/support/compilers.html current release] and [https://www.mathworks.com/support/sysreq/previous_releases.html previous releases] are available online. Many of the supported {{ic|gcc}}, {{ic|g++}}, {{ic|jdk}} compiler versions for past MATLAB releases are available from the [[AUR]] (e.g., {{AUR|gcc43}}, {{AUR|gcc44}}, {{AUR|gcc47}}, {{AUR|gcc49}}and {{AUR|jdk7}}), while past versions of the {{ic|gfortran}} compilers are not packaged.<br />
<br />
To use previous versions of the {{ic|gcc}}, {{ic|g++}}, and {{ic|gfortran}} compilers with MEX files, edit {{ic|${MATLAB}/bin/mexopts.sh}} and replace all occurrences of {{ic|<nowiki>CC='gcc'</nowiki>}} with {{ic|<nowiki>CC='gcc-4.X'</nowiki>}}, {{ic|<nowiki>CXX='g++'</nowiki>}} with {{ic|<nowiki>CXX='g++-4.X'</nowiki>}}, and {{ic|<nowiki>FC='gfortran'</nowiki>}} with {{ic|<nowiki>FC='gfortran-4.X'</nowiki>}}, where {{ic|X}} is the compiler version appropriate for the particular MATLAB release.<br />
<br />
{{Note|<br />
* Newer versions of Matlab (at least 2017a) does not seem to respect the {{ic|${MATLAB}/bin/mexopts.sh}} customization. Instead it uses {{ic|${MATLAB}/bin/glnxa64/mexopts/LANG_glnxa64.xml}} file.<br />
* Though, it is not officially supported, one could still use higher version of compiler, and ignore the warnings.<br />
}}<br />
<br />
=== Help browser ===<br />
<br />
The help browser uses valuable slots in the dynamic thread vector and causes competition with core functionality provided by libraries like the BLAS that also depend on the dynamic thread vector. The help browser can be configured to use fewer slots in the dynamic thread vector with<br />
<br />
>> webutils.htmlrenderer('basic');<br />
<br />
This is a persistent change and to reverse it use<br />
<br />
>> webutils.htmlrenderer('default');<br />
<br />
=== Serial port access ===<br />
<br />
To successfully connect to any serial port, MATLAB expects to have write access directly to {{ic|/var/lock}} which is not allowed on Arch Linux for security reasons. Instead of allowing this access just for MATLAB, you can work around this problem by redirecting device locking using {{AUR|lockdev-redirect}}. All you have to do is executing MATLAB like this:<br />
<br />
# lockdev-redirect /{MATLAB}/bin/matlab<br />
<br />
If you have created a .desktop file as shortcut to MATLAB, then add "lockdev-redirect" as a prefix to your "Exec=" entry.<br />
<br />
=== HiDPI and 4k ===<br />
<br />
See [[HiDPI#MATLAB]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Warning: Initializing MATLAB Graphics failed ===<br />
<br />
This error seems to happen on multi-monitor setups, see [https://www.mathworks.com/matlabcentral/answers/611786-warning-initializing-matlab-graphics-failed#comment_1131148 this forum post].<br />
<br />
=== Blackscreen in help browser and livescripts ===<br />
<br />
In order to use help browser and livescripts install {{aur|libselinux}}.<br />
<br />
=== Static TLS errors ===<br />
<br />
MATLAB has a number of libraries that have been compiled with static thread local storage (TLS) including the help browser {{ic|doc}} and the BLAS libraries. For example,<br />
<br />
>> doc('help');<br />
>> ones(10)*randn(10);<br />
Error using * <br />
BLAS loading error:<br />
dlopen: cannot load any more object with static TLS<br />
<br />
is related to the bugs:<br />
<br />
* [https://www.mathworks.de/support/bugreports/961964 961964] for which patched libraries are available from [http://www.mathworks.de/support/bugreports/license/accept_license/5730?fname=attachment_961964_12b_13a_13b_14a_glnxa64_2014-01-30.zip&geck_id=961964 MathWorks]{{Dead link|2020|03|30|status=404}}<br />
* [https://www.mathworks.com/support/bugreports/1003952 1003952] for which workarounds exist<br />
<br />
A more general solution of recompiling {{ic|glibc}} has also been suggested. [https://stackoverflow.com/a/19468365]<br />
<br />
=== Blank/grey UI when using WM (non-reparenting window manager) ===<br />
<br />
See [[Java#Gray window, applications not resizing with WM, menus immediately closing]].<br />
<br />
=== Corrupted text and fonts in menus and fields ===<br />
<br />
If you notice that the menus or the input fields are corrupted or not appearing correctly then you can try to activate the ''"'''Use antialiasing to smooth desktop fonts'''"'' option in Matlab preferences, it seems to solve the problem. Go to '''''Preferences -> Matlab -> Fonts''''' and activate it. You will need to restart Matlab in order to take affect.<br />
<br />
=== Installation dependencies missing ===<br />
<br />
Matlab might complain that it cannot find a package. Look at the package name and install it with [[Pacman]], or in the case of x86_64 there are some libraries only in [[AUR]]. {{AUR|matlab}} and {{AUR|matlab-dummy}} packages contain a list of up-to-date dependencies for the newest Matlab version.<br />
<br />
See also [[#Unable to launch the MATLABWindow application]].<br />
<br />
=== Installation error: archive is not a ZIP archive ===<br />
<br />
During the installation you can get:<br />
<br />
The following error was detected while installing ''package_name'': archive is not a ZIP archive <br />
Would you like to retry installing ''package_name''? If you press No, the installer will exit without completing the installation. More information can be found at /tmp/mathworks_root.log<br />
<br />
Matlab downloads all packages to {{ic|/tmp/}} directory which resides in RAM and is maximum size of half of available memory. In this case it is not enough for installation files and Matlab 2019a installer will warn you about this. If it did not, or if you ignored the warning, you will have got the above error.<br />
<br />
You can either [[Tmpfs#Examples|resize tmpfs]] (3,5 GB is not enough, 6 GB works), or remove packages from base install and add them later with built-in Matlab add-on installer.<br />
<br />
=== Install-time library errors ===<br />
<br />
* Make sure that the symlink {{ic|bin/glnx64/libstdc++.so.6}} is pointing to the correct version of {{ic|libstdc++.so.xx}} (which is also in the same directory and has numbers where 'xx' is). By default, it may be pointing to an older (and nonexistent) version (different value for 'xx').<br />
<br />
* Make sure the device you are installing from is not mounted as {{ic|noexec}}<br />
<br />
* If you downloaded the files from Mathworks' website, make sure they are not on an NTFS or FAT partition, because that can mess up the symlinks. Ext4 or Ext3 should work.<br />
<br />
=== Hangs on rendering or exiting with Intel graphics ===<br />
<br />
Some users have reported issues with DRI3 enabled on Intel Graphics chips. A possible workaround is to disable DRI3 and run MATLAB with hardware rendering on DRI2; to do so, launch MATLAB with the environment variable LIBGL_DRI3_DISABLE set to 1:<br />
<br />
LIBGL_DRI3_DISABLE=1 /{MATLAB}/bin/matlab<br />
<br />
If the previous workaround does not work, the issue can be circumvented by selecting software rendering with the MATLAB command (beware, performance may be very poor when doing e.g. big or complex 3D plots):<br />
<br />
opengl('save','software')<br />
<br />
See [https://bugzilla.redhat.com/show_bug.cgi?id=1357571] and [https://bugs.freedesktop.org/show_bug.cgi?id=96671] for more.<br />
<br />
=== LiveScript errors ===<br />
<br />
If you get the error when attempting to load or create a LiveScript:<br />
{{ic|Viewing matlab live script files is not currently supported by this operating system configuration}}<br />
*It could be because of broken symlinks of {{Pkg|libgcrypt}} and other dependencies, after system updates. On the first start of the Live Editor the components are extracted and these libary symlinks are created (if not existing).<br />
: A solution is to simply delete the whole folder containing the broken symlinks and the extracted components, which are in the installation directory:<br />
''matlab_root''/sys/jxbrowser-chromium<br />
: Or, if the installation directory is not user writable, then in:<br />
~/.matlab/R2017b/HtmlPanel<br />
: Matlab will then regenerate the contents on the next Live Editor start.<br />
: A better option is to replace libgcrypt symlink in this extraction directory with a less precise one. For example, after extraction, this link to /lib64/libgcrypt.so.20.2.4 is created. Replace it with e.g. /lib64/libgcrypt.so.20.<br />
: Matlab R2020 does not contain a chromium directory anymore. Relinking the library file libcrypto.so.1.1 with the system file can resolve the issue. It is located in:<br />
''matlab_root''/bin/glnxa64<br />
*Also the steps in [[#Unable to launch the MATLABWindow application]] may resolve the issue.<br />
*It can also happen due to missing gconf package. Make sure {{AUR|gconf}} is installed.<br />
*If the above does not help, execute in the command window<br />
>> com.mathworks.mde.liveeditor.widget.rtc.CachedLightweightBrowserFactory.createLightweightBrowser()<br />
to get a more detailed error message.<br />
* A debugging console can be opened with<br />
>> com.mathworks.mde.webbrowser.HtmlPanelDebugConsole.invoke;<br />
<br />
=== Using webcam/video device ===<br />
<br />
Make sure the correct support package add-ons are installed (webcam or OS Generic Video Interface for example). If running matlab as a user, make sure your user has write permissions to wherever the support packages are being downloaded and installed.<br />
<br />
Since MATLAB R2017a, Image Acqusition Toolbox is using GStreamer library version 1.0. It previously used version 0.10.<br />
<br />
In general, USB Webcam Support Package does a better job working with UVC and built-in cameras than OS Generic Video Interface Support Package.<br />
<br />
=== MATLAB hangs for several minutes when closing Help Browser ===<br />
<br />
{{Style|Written in first person}}<br />
<br />
Since upgrade of glibc from 2.24 to 2.25, MATLAB (at least R2017a) hangs when closing Help Browser. The issue is related to the particular version of jxbrowser-chromium shipped with MATLAB.<br />
This issue is still present with glibc 2.26 and MATLAB R2017b and R2018a.<br />
<br />
To fix this issue, download the [https://www.teamdev.com/jxbrowser latest jxbrowser] and replace the following jars from MATLAB:<br />
<br />
''matlab_root''/java/jarext/jxbrowser-chromium/jxbrowser-chromium.jar<br />
''matlab_root''/java/jarext/jxbrowser-chromium/jxbrowser-linux64.jar<br />
<br />
MATLAB should automatically unpack those jars into {{ic|''matlab_root''/sys/jxbrowser-chromium/glnxa64/chromium}} when first opening Help Browser.<br />
Remove {{ic|''matlab_root''/sys/jxbrowser-chromium/glnxa64/chromium}} directory to make sure MATLAB uses the latest jxbrowser.<br />
<br />
Unfortunately, this workaround does not work in R2017b anymore. Going deeper into investigation of this issue, it is related to a crash of one of jxbrowser-chromium processes. The parent process of jxbrowser-chromium then sits there and waits for response from a process that is already dead. This causes MATLAB main window to freeze. You can easily unfreeze MATLAB by manually killing all leftover jxbrowser-chromium processes.<br />
<br />
I have come up with this simple script that uses inotify and waits for user to close Help browser in MATLAB. It triggers when user closes Help browser and sends kill signal to all leftover jxbrowser-chromium processes:<br />
<br />
{{bc|1=<br />
#!/bin/sh<br />
<br />
if [ -z "$1" ]; then<br />
REL=R2017b<br />
else<br />
REL=$1<br />
fi<br />
<br />
JXPATH="/path/to/MATLAB/$REL/sys/jxbrowser-chromium/glnxa64/chromium"<br />
CMD="inotifywait -m -e CLOSE $JXPATH/resources.pak"<br />
<br />
#Exit if the daemon is already active<br />
if ! pgrep -f "$CMD" > /dev/null; then<br />
#Wait for user to close Help Browser, then killall leftover jxbrowser processes<br />
$CMD {{!}}<br />
while read line<br />
do<br />
killall "$JXPATH/jxbrowser-chromium"<br />
done<br />
else<br />
exit<br />
fi<br />
}}<br />
<br />
I run this script as part of my MATLAB start script like that:<br />
~/bin/unfreeze_matlab.sh R2017b &<br />
<br />
To make sure that this background job is killed when I exit MATLAB, I use this in the beginning of MATLAB start script:<br />
trap "trap - SIGTERM && kill -- -$$" SIGINT SIGTERM EXIT<br />
<br />
=== Some dropdown menus cannot be selected ===<br />
<br />
In some interfaces - such as Simulation Data Inspector or Simulink Test Manager - nothing happens when choosing an item in dropdown menu (for example, when trying to change a number of subplots in Simulation Data Inspector). To work around this issue, hold down the Shift key while clicking the item in dropdown menu.<br />
<br />
=== Not starting - licensing error ===<br />
<br />
In case MATLAB will not start from a [[desktop environment]] by the call of its [[desktop file]] one should see the output as you start it from the terminal.<br />
<br />
For a ''Licensing error'' such as:<br />
<br />
{{hc|# matlab|<nowiki><br />
MATLAB is selecting SOFTWARE OPENGL rendering.<br />
License checkout failed.<br />
License Manager Error -9<br />
This error may occur when: <br />
-The hostid of this computer does not match the hostid in the license file. <br />
-A Designated Computer installation is in use by another user. <br />
If no other user is currently running MATLAB, you may need to activate.<br />
<br />
Troubleshoot this issue by visiting: <br />
https://www.mathworks.com/support/lme/R2017a/9<br />
<br />
Diagnostic Information:<br />
Feature: MATLAB <br />
License path: /home/<USER>/.matlab/R2017a_licenses/license_<NUM>_R2017a.lic:/home/<USER>/.matlab/R2017a_licenses/lice<br />
nse_Darkness_<NUM>_R2017a.lic:/opt/MATLAB/R2017a/licenses/license.dat:/opt/MATLAB/R2017a/licenses/*<br />
.lic <br />
Licensing error: -9,57.<br />
</nowiki>}}<br />
<br />
A re-activation might solve the problem.<br />
<br />
/usr/local/MATLAB/R2017a/bin/activate_matlab.sh -javadir /usr/lib/jvm/java-8-openjdk/jre/<br />
<br />
=== MATLAB crashes with "Failure loading desktop class" on startup ===<br />
<br />
In case MATLAB will not start and starting it from command line gives you the following error:<br />
{{hc<br />
|$ matlab|<br />
Fatal Internal Error: Internal Error: Failure occurs during desktop startup. Details: Failure loading desktop class.<br />
}}<br />
and you have the option [[Java#GTK LookAndFeel|-Dswing.defaultlaf=com.sun.java.swing.plaf.gtk.GTKLookAndFeel]] set in your {{ic|_JAVA_OPTIONS}} environment variable, start MATLAB with<br />
<br />
$ _JAVA_OPTIONS= matlab<br />
<br />
If this works, add the line<br />
<br />
export _JAVA_OPTIONS=<br />
<br />
to your MATLAB launcher script. Optionally re-add other Java options.<br />
<br />
=== Unable to type in text fields of interfaces based on MATLABWindow ===<br />
<br />
{{Style|Written in first person}}<br />
Since R2018a, it is not possible to type text in interfaces based on MATLABWindow - like Signal Editor, Add-Ons Explorer and others.<br />
MATLABWindow and MATLAB's webwindow infrastructure is based on Chromium Embedded Framework, and it looks like a known and long standing bug: https://bitbucket.org/chromiumembedded/cef/issues/2026/multiple-major-keyboard-focus-issues-on<br />
<br />
One possible workaround is to switch focus from the MATLABWindow to another window and then switch back - so that you can type.<br />
<br />
To elaborate more on this workaround (since the problem is still there in R2018b), here is what i did in my Openbox config (note that the A-Middle keybinding already exist in default config):<br />
<br />
<mousebind button="A-Middle" action="Press"><br />
<action name="Unfocus"/><br />
<action name="Focus"/><br />
</mousebind><br />
<br />
Now, whenever it is not possible to type in a text field, I press Alt+Mouse middle mouse and then I can type again.<br />
<br />
This problem is critical during installation. After one clicks some elements in the installation window, he will not be able to type into any textbox anymore and switching between windows does not always work. To circumvent the issue, one shall only use key-press, instead of mouse click during installation. MATLAB installer has a poor support on Wayland, one may also consider using other WM instead during installation.<br />
<br />
=== Unable to launch the MATLABWindow application ===<br />
<br />
In MATLAB versions R2018b until R2022b, the installer crashes as follows:<br />
<br />
{{hc<br />
| $ ./install |<br />
terminate called after throwing an instance of 'std::runtime_error'<br />
what(): Failed to launch web window with error: Unable to launch the MATLABWindow application. The exit code was: 127<br />
[1] 1409378 IOT instruction (core dumped) ./install<br />
}}<br />
<br />
To find out why {{ic|MATLABWindow}} is crashing, run it manually to get detailed information.<br />
<br />
{{hc<br />
| $ ./bin/glnxa64/MATLABWindow |<br />
bin/glnxa64/MATLABWindow: symbol lookup error: /usr/lib/libcairo.so.2: undefined symbol: FT_Get_Color_Glyph_Layer<br />
}}<br />
<br />
{{ic|FT_Get_Color_Glyph_Layer}} is a symbol of {{Pkg|freetype2}}, which indicates a library incompatibility between the MATLAB application and the Arch Linux packages. [https://ww2.mathworks.cn/matlabcentral/answers/364551-why-is-matlab-unable-to-run-the-matlabwindow-application-on-linux]<br />
<br />
To fix this, put aside MATLAB's {{ic|libfreetype.so*}}.<br />
<br />
$ rm ./bin/glnxa64/libfreetype.so*<br />
<br />
You can also use {{ic|LD_PRELOAD}} environment variable to force MATLAB use Arch Linux's libfreetype without removing the lib file.<br />
<br />
$ export LD_PRELOAD=/lib64/libfreetype.so<br />
$ ./install<br />
<br />
Similarly, if the error is caused by {{ic|undefined symbol: g_log_structured...}}, put aside MATLAB's {{ic|libglib-2.0.so*}}. If the error is caused by {{ic|path to/libstdc++.so.6: version `CXXABI_1.3.9' not found (required by _somelibrary_)}}, put aside MATLAB's {{ic|libstdc++.so.6}}.<br />
<br />
=== Cannot verify university login during installation ===<br />
<br />
For total headcount license users, MATLAB will pop-up a window asking the user to login with their credentials in a web browser. However, if run with {{ic|sudo}}, most browsers (especially chromium) will not run. To circumvent this problem, one shall 'active the computer' through MATLAB's website using a browser by a normal user. [https://www.mathworks.com/matlabcentral/answers/326647-verify-university-login-not-open-browser See this issue]<br />
<br />
=== Missing libcrypt.so.1 ===<br />
<br />
If you get this error when launching or installing MATLAB (R2020a and later), install {{Pkg|libxcrypt-compat}}.<br />
<br />
=== Running installer as root does not launch the GUI ===<br />
<br />
If you run the installer as root and the GUI does not appear (but does appear without launching as root), try temporarily allowing the root user to access the X Server by running the following commands in order (where {{ic|./install}} is the command to run the installer as root):<br />
<br />
$ xhost +SI:localuser:root<br />
# ./install<br />
$ xhost -SI:localuser:root<br />
<br />
Note that the last command should be executed upon finishing the installation process, and {{ic|localuser}} is a string literal. See [https://au.mathworks.com/matlabcentral/answers/1461039-on-ubuntu-sudo-won-t-run-the-install-file#comment_1782671 this support answer], and {{man|1|xhost}}.<br />
<br />
In addition, verify that the {{ic|DISPLAY}} environment variable is set.<br />
<br />
An alternative is to install MATLAB as a local user.<br />
<br />
=== GUI installer is unable to create the target folder when installing as user ===<br />
<br />
Make the folder manually (as root), and take ownership. The path is typically /usr/local/MATLAB<br />
# mkdir -p /path/to/MATLAB/R20XXx<br />
# chown -R $LOGNAME: /path/to/MATLAB/R20XXx<br />
<br />
=== MATLAB crashes when opening Simulink ===<br />
<br />
When running from terminal the error message is:<br />
<br />
Inconsistency detected by ld.so: ../elf/dl-tls.c: 597: _dl_allocate_tls_init: Assertion `listp != NULL' failed!<br />
<br />
See upstream bug report here: https://www.mathworks.com/support/bugreports/details/2632298<br />
<br />
=== MATLAB cannot open or create script files ===<br />
<br />
See [[#Unable to launch the MATLABWindow application]].<br />
<br />
=== Calls to mex fail ===<br />
<br />
If calls from MATLAB or Simulink to mex (e.g. rapid accelerator) fail with the error {{ic|*.mexa64 is not a MEX file}}, even though the resulting file is usable, it may help to edit {{ic|}} in either {{ic|matlab/bin/}} or {{ic|~/.matlab7rc.sh}} by changing the {{ic|LDPATH_PREFIX}} variable from its empty default: [https://github.com/alecjacobson/matlab/blob/883d417a99fcb8ead89387cee243e51a92864019/bin/.matlab7rc.sh#L170]<br />
<br />
{{hc|matlab/bin/.matlab7rc.sh (or ~/.matlab7rc.sh)|2=<br />
...<br />
case "$ARCH" in<br />
'''glnx*)''' # Make sure you are modifying case '''glnx*'''<br />
AUTOMOUNT_MAP=<nowiki>''</nowiki><br />
DISPLAY="$DISPLAY"<br />
ARCH="$ARCH"<br />
TOOLBOX="$TOOLBOX"<br />
MATLABPATH="$MATLABPATH"<br />
SHELL="$SHELL"<br />
'''LDPATH_PREFIX='/usr/lib' '''<br />
...<br />
}}<br />
<br />
=== Incompatibilities with some python libraries using MKL ===<br />
<br />
Some python code running inside matlab may fail with an error mentioning {{ic|Parameter * was incorrect on entry to }}. This can be avoided by calling<br />
py.sys.setdlopenflags(int32(bitor(int64(py.os.RTLD_NOW), int64(py.os.RTLD_DEEPBIND))));<br />
or<br />
py.sys.setdlopenflags(int32(bitor(int64(py.os.RTLD_LAZY), int64(py.os.RTLD_DEEPBIND))));<br />
directly before any calls to {{ic|py}} and after calls to {{ic|pyenv}}.<br />
See [https://www.mathworks.com/matlabcentral/answers/358233-matlab-python-interface-broken?s_tid=email_ans_new_ans_ans_h#answer_283353 this support answer].<br />
<br />
=== Settings not persisting between MATLAB restarts ===<br />
<br />
In some cases on recent Arch systems matlab is unable to export {{ic|.mlsettings}} files, preventing toolbox and some matlab settings from being saved to disk and persisted. These cases come from matlab trying to hard link new files from {{ic|/tmp}} directly to the preferences directory (usually {{ic|~/.matlab/release}} where {{ic|release}} is the matlab version, e.g. {{ic|R2021b}}). As a workaround, run matlab with the {{ic|$TMPDIR}} environment variable set to a folder on the same file system as the preferences directory. [https://www.mathworks.com/matlabcentral/answers/1777865-matlab-preferences-not-being-saved-across-sessions]<br />
<br />
=== "Unable to open this file in the current system configuration" ===<br />
<br />
The error can be fixed by setting aside the l{{ic|ibfreetype.so.6}} in {{ic|''matlab_root''/bin/glnxa64/}}. You may run the following command:<br />
<br />
cd ''matlab_root''/bin/glnxa64/<br />
mv libfreetype.so.6 libfreetype.so.6.old<br />
<br />
=== Symbols in toolstrip menus are not diplayed properly ===<br />
<br />
{{Expansion|Explain which symbols are needed, so that users can choose any font providing them.}}<br />
<br />
This issue can be fixed by [[install]]ing {{Pkg|noto-fonts}}.<br />
<br />
=== Blank screen on Xwayland ===<br />
As suggested in [[Wayland#Java]], this issue can be fixed by adding in the Matlab launcher script:<br />
export _JAVA_AWT_WM_NONREPARENTING=1<br />
<br />
== MATLAB in a systemd-nspawn ==<br />
<br />
MATLAB can be run within a systemd-nspawn container to maintain a static system and avoid the library issues that often plague matlab installs after significant updates to libraries in Arch. Refer to [[Systemd-nspawn]] for detailed information on setting up such containers.<br />
<br />
The following instruction is to get a MATLAB R2021b installation running in a minimal Debian 11 environment. It assumes MATLAB is already installed as normal in "/usr/local/MATLAB/R2021b".<br />
<br />
Use [[Xhost]] to allow the nspawn environment to use the existing X server instance, see also [[Systemd-nspawn#Use an X environment]].<br />
<br />
Create a minimal Debian environment in a directory ("deb11" here) with:<br />
<br />
$ debootstrap --include=systemd-container --components=main,contrib bullseye deb11<br />
<br />
Set a password for the root user and create regular user:<br />
<br />
$ systemd-nspawn -D deb11<br />
passwd<br />
useradd -m username<br />
logout<br />
<br />
and then boot the environment with:<br />
<br />
$ systemd-nspawn --bind-ro=/dev/dri --bind-ro=/tmp/.X11-unix --bind=/dev/shm --bind=/usr/local/MATLAB --setenv=DISPLAY=:0 --setenv=MESA_LOADER_DRIVER_OVERRIDE=i965 -b -D deb11<br />
<br />
Install the following packages to have the required libraries in the nspawn environment for MATLAB: https://github.com/mathworks-ref-arch/container-images/blob/master/matlab-deps/r2021b/ubuntu20.04/Dockerfile<br />
<br />
"mesa-utils" and dependencies needs to be installed to support graphics acceleration.<br />
"usbutils" can be installed to support usb interfaces for I/O with MATLAB.<br />
<br />
Install the matlab-support (from contrib source) package in the environment for some convenient integration. <br />
<br />
$ apt-get install matlab-support<br />
<br />
MATLAB can be launched from within the environment normally by using the binary at {{ic|''matlab_root''/bin}}.<br />
<br />
Another way is to add something like <br />
-u username -a /usr/local/MATLAB/R2021b/bin/matlab -nosoftwareopengl -useStartupFolderPref<br />
<br />
to the systemd-nspawn command above.</div>Ondrianhttps://wiki.archlinux.org/index.php?title=MATLAB&diff=800057MATLAB2024-02-09T10:33:23Z<p>Ondrian: Link to official docs of MPM.</p>
<hr />
<div>[[Category:Numerical analysis]]<br />
[[ja:MATLAB]]<br />
[[zh-hans:MATLAB]]<br />
{{Related articles start}}<br />
{{Related|Octave}}<br />
{{Related|Sage-mathematics}}<br />
{{Related|Mathematica}}<br />
{{Related articles end}}<br />
{{Style|unnecessarily verbose, sometimes written in in first person}}<br />
From the [https://www.mathworks.com/products/matlab.html official website]:<br />
<br />
:MATLAB is a programming and numeric computing platform used by millions of engineers and scientists to analyze data, develop algorithms, and create models.<br />
<br />
== Overview ==<br />
<br />
MATLAB is proprietary software produced by The MathWorks and requires a license to obtain, install, and activate. New versions of MATLAB are released twice a year,<br />
release names are composed of {{ic|R}}, the year of the release and {{ic|a}} or {{ic|b}}.<br />
Arch Linux is not officially supported.<br />
[https://www.mathworks.com/support/requirements/matlab-linux.html]<br />
<br />
== Installation ==<br />
<br />
A complete copy of the MATLAB software must be obtained before it can be installed. The MATLAB software is available to licenses holders on both a DVD and through the [https://www.mathworks.com MathWorks website]. In addition to the software a file installation key is required for installation. It is possible to install MATLAB either with the {{AUR|matlab}} package or from the MATLAB installation software directly. The advantage of the {{AUR|matlab}} package is that it manages dependencies and some of the nuances of the installation process while installing directly from the MATLAB installation software can be done by regular users to their home directories.<br />
<br />
=== Installing from the MATLAB installation software ===<br />
<br />
The MATLAB installation software is self contained and does not require any additional packages to install in silent mode. To install with the GUI a working [[Xorg]] graphical display is necessary. [[Wayland]] is not officially supported yet, so it will run in a Xwayland session. The installation is handled by the {{ic|install}} script. You can run the script as root to install MATLAB system-wide or your user to install it only for you.<br />
<br />
During the installation, you are asked if you want symlinks to be created. If you did not choose to do so, you can now manually create a symlink in {{ic|/usr/local/bin}} to make it easier to launch in terminal:<br />
<br />
# ln -s /{MATLAB}/bin/matlab /usr/local/bin<br />
<br />
Or you could add MATLAB install path to {{ic|PATH}} environment variable.<br />
<br />
{{Note|If the installation crashes with {{ic|Failed to launch web window with error: Unable to launch the MATLABWindow application.}}, see [[#Unable to launch the MATLABWindow application]] for a workaround.}}<br />
<br />
=== Installing with MATLAB Package Manager (MPM) ===<br />
<br />
[https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md MATLAB Package Manager] (MPM) offers a streamlined method to install MATLAB and accompanying MathWorks products on Linux systems, directly from the command line. This utility facilitates programmatic installation without necessitating user sign-in, a File Installation Key, or a pre-acquired license file, deferring activation and licensing to post-installation. MPM permits specification of MATLAB release version, additional toolboxes, and installation directory. Additionally, it serves well for constructing MATLAB Docker containers. As of 2023, the MATLAB installer does not support Wayland, and this is an easy way to install MATLAB via command-line.<br />
<br />
Here's how to acquire MPM and set it up for execution (ensure wget is installed):<br />
<br />
{{hc|wget https://www.mathworks.com/mpm/glnxa64/mpm|chmod +x mpm}}<br />
<br />
Installation of MATLAB and desired products is conducted with the following syntax:<br />
<br />
./mpm install --release=<release> --destination=<destination> [--products] <product1> <product2> [...]<br />
<br />
For instance, to install MATLAB R2021b along with select toolboxes to a specified directory, the command would be:<br />
<br />
/mpm install --release=R2021b --destination=/home/username/matlab MATLAB Simulink Deep_Learning_Toolbox Parallel_Computing_Toolbox<br />
<br />
==== Desktop entry ====<br />
<br />
Optionally create a [[desktop entry]]. The MIME type of MATLAB files is {{ic|text/x-matlab}}.<br />
<br />
Start {{ic|matlab}} with:<br />
<br />
* {{ic|-desktop}} to run Matlab without a terminal.<br />
* {{ic|-nosplash}} to prevent the splash screen from showing up.<br />
<br />
In order for icons to appear correctly {{ic|StartupWMClass}} needs to be set in the desktop entry. To find it out start MATLAB, run {{ic|xprop {{!}} grep WM_CLASS}} and select the MATLAB window.<br />
<br />
Example desktop entry: <br />
<br />
{{hc|/usr/share/applications/matlab.desktop|2=<br />
[Desktop Entry]<br />
Type=Application<br />
Terminal=false<br />
MimeType=text/x-matlab<br />
Exec=/usr/local/MATLAB/R20''xyz''/bin/matlab -desktop<br />
Name=MATLAB<br />
Icon=matlab<br />
Categories=Development;Math;Science<br />
Comment=Scientific computing environment<br />
StartupNotify=true<br />
}}<br />
<br />
If one need to set environment variable, one could prepend {{ic|env}} in {{ic|Exec}}, for example, to system's libfreetype:<br />
<br />
Exec=env LD_PRELOAD=/usr/lib/libfreetype.so.6 matlab<br />
<br />
One might want to use the system's {{ic|libstdc++}}.<br />
<br />
=== Installing from the AUR package ===<br />
<br />
The {{AUR|matlab}} package is designed to allow MATLAB to be integrated into and managed by Arch. Note however, that the package does not contain the installation files, and you are expected to place them in the cloned package folder yourself. It can be problematic to build the package using [[AUR helpers]], so you are expected to do so manually. You can obtain the actual MATLAB software using the installer from [https://www.mathworks.com the MathWorks website].<br />
<br />
{{Warning|The EULA for the proprietary MATLAB software is restrictive and it prohibits distribution and modification of the installation files. The installation method described in this section should only be performed on the system on which the software is going to be installed and the package should be deleted from the installation location and the [[pacman]] cache following installation. Redistributing the built package is a violation of the MATLAB EULA.}}<br />
<br />
* Clone the {{AUR|matlab}} package and {{ic|cd}} into it.<br />
* Download the zip file containing the MATLAB installer from MathWorks into the current directory. Extract the zip to the {{ic|matlab}} subdirectory:<br />
$ bsdtar xC matlab -f matlab_''XXXXX''_glnxa64.zip<br />
* Run the extracted installer with:<br />
$ ./matlab/install<br />
* The installer gives you a choice of either installing the software now or only downloading selected modules. Choose the second option. This option may also be under the "Advanced Options" dropdown menu.<br />
* The installer will give you an option to change the download path. You might want to change it to something temporary (like {{ic|/tmp}} if you have big enough ram disk) as you will soon move the contents to a different location.<br />
* Wait for the download to finish and close the installer. Merge the downloaded archives into the extracted {{ic|matlab}} subdirectory:<br />
$ rsync -a /selected/download/folder/''YYYY_MM_DD_HH_MM_SS''/ matlab<br />
* Then package the directory into a tarball:<br />
$ tar -cvf matlab.tar matlab<br />
* Download your licence:Go to [https://mathworks.com/mwaccount/ your MathWorks account] and click on the licence number you want to use. Then, go to the ''Install and activate'' tab and select ''Activate to retrieve licence File''. Follow the instructions and download the licence file needed for the installation. Name the file {{ic|matlab.lic}} and place it in the AUR package directory. There will also be a File Installation Key (FIK) visible on the MathWorks website. Copy-paste it in a new file named {{ic|matlab.fik}} and save it next to {{ic|PKGBUILD}} just like you did with the {{ic|matlab.lic}}.<br />
* Now, you will create a pacman package. You can customize the modules you want the package to contain by modifying the {{ic|PKGBUILD}} or leave it at default:<br />
{{hc|PKGBUILD|2=<br />
...<br />
# Limit products to lower size, set this to true to do a partial install<br />
partialinstall=false<br />
# Example list of products for a partial install; check README.md for details<br />
products=(<br />
"MATLAB"<br />
#---MATLAB Product Family---#<br />
"Curve_Fitting_Toolbox" # Math and Optimization<br />
"Database_Toolbox" # Database Access and Reporting<br />
"Deep_Learning_HDL_Toolbox"<br />
"Deep_Learning_Toolbox"<br />
"DSP_System_Toolbox"<br />
"Global_Optimization_Toolbox"<br />
"GPU_Coder"<br />
"MATLAB_Coder" # Code Generation<br />
"MATLAB_Compiler" # Application Deployement<br />
"MATLAB_Compiler_SDK"<br />
"Optimization_Toolbox"<br />
"Parallel_Computing_Toolbox" # Parallel computing<br />
"Partial_Differential_Equation_Toolbox"<br />
"Reinforcement_Learning_Toolbox"<br />
"Statistics_and_Machine_Learning_Toolbox" # AI, Data Science, Statistics<br />
"Symbolic_Math_Toolbox"<br />
"Text_Analytics_Toolbox"<br />
#---Application Products---#<br />
"Audio_Toolbox"<br />
"Bioinformatics_Toolbox" # Computational Biology<br />
"Computer_Vision_Toolbox"<br />
"Image_Processing_Toolbox" # Image Processing and Computer Vision<br />
"Signal_Processing_Toolbox" # Signal Processing<br />
"Wavelet_Toolbox"<br />
)<br />
...<br />
}}<br />
* Finally, use {{ic|makepkg}} command to build and install the package:<br />
$ makepkg -sri<br />
<br />
== Configuration ==<br />
<br />
=== Java ===<br />
<br />
The MATLAB software is bundled with a JVM and therefore it is not necessary to install [[Java]]. The JVM version supported by MATLAB is listed in [https://ww2.mathworks.cn/support/compilers.html System Requirements & Platform Availability] or simply type {{ic|version -java}} in MATLAB. One could set the {{ic|MATLAB_JAVA}} environment variable to use custom JVM, for example, to specify the {{pkg|jre8-openjdk}} JRE, launch MATLAB with:<br />
<br />
$ env MATLAB_JAVA=/usr/lib/jvm/java-8-openjdk/jre matlab<br />
<br />
=== OpenGL acceleration ===<br />
<br />
MATLAB can take advantage of hardware based 2D and 3D OpenGL acceleration. Support for hardware acceleration needs to be configured outside of MATLAB. Appropriate [[video drivers]] need to be installed along with the OpenGL utility library {{Pkg|glu}} package. If X11 forwarding is being used, the video drivers need to be installed on both the client and server. To check if MATLAB is making use of hardware based OpenGL acceleration run:<br />
<br />
$ matlab -nodesktop -nosplash -r "opengl info; exit" | grep Software<br />
<br />
If "software rendering" is not "false", then there is a problem with your hardware acceleration. If this is the case make sure OpenGL is configured correctly on the system. This can be done with the {{ic|glxinfo}} program from the {{Pkg|mesa-utils}} package:<br />
<br />
$ glxinfo | grep "direct rendering"<br />
<br />
If "direct rendering" is not "yes", then there is likely a problem with your system configuration.<br />
<br />
If glxinfo works but not matlab, you can try to run:<br />
<br />
$ export LD_PRELOAD=/usr/lib/libstdc++.so; export LD_LIBRARY_PATH=/usr/lib/xorg/modules/dri/; matlab -nodesktop -nosplash -r "opengl info; exit" | grep Software<br />
<br />
If it works, you can edit Matlab launcher script to add:<br />
<br />
export LD_PRELOAD=/usr/lib/libstdc++.so<br />
export LD_LIBRARY_PATH=/usr/lib/dri/<br />
<br />
After these changes, you may see low-level graphics errors in the MATLAB console such as:<br />
<br />
com.jogamp.opengl.GLException: X11GLXDrawableFactory - Could not initialize shared resources for X11GraphicsDevice[type .x11, connection :0, unitID 0, handle 0x0, owner false, ResourceToolkitLock[obj 0x76ddc7cd, isOwner false, <6876ff80, 5d5c50dc>[count 0, qsz 0, owner <NULL>]]]<br />
at jogamp.opengl.x11.glx.X11GLXDrawableFactory$SharedResourceImplementation.createSharedResource(X11GLXDrawableFactory.java:326)<br />
at jogamp.opengl.SharedResourceRunner.run(SharedResourceRunner.java:297)<br />
at java.lang.Thread.run(Thread.java:748)<br />
Caused by: java.lang.NullPointerException<br />
at jogamp.opengl.GLContextImpl.makeCurrent(GLContextImpl.java:688)<br />
at jogamp.opengl.GLContextImpl.makeCurrent(GLContextImpl.java:580)<br />
at jogamp.opengl.x11.glx.X11GLXDrawableFactory$SharedResourceImplementation.createSharedResource(X11GLXDrawableFactory.java:297)<br />
... 2 more<br />
<br />
In that case, create a file with the name 'java.opts' in the directory where MATLAB is executed (for example {{ic|/usr/local/MATLAB/R2020a/bin/glnxa64}}) with the following line:<br />
<br />
{{hc|java.opts|2=<br />
-Djogl.disable.openglarbcontext=1<br />
}}<br />
<br />
=== Sound ===<br />
<br />
To confirm that MATLAB is able to use the default soundcard to present sounds run:<br />
<br />
$ matlab -nodesktop -nosplash -r "load handel; sound(y, Fs); pause(length(y)/Fs); exit" > /dev/null<br />
<br />
This should play an except from Handel's "Hallelujah Chorus." If this fails make sure [[ALSA]] is properly configured. This can be done with the {{ic|speaker-test}} program from the {{Pkg|alsa-utils}} package:<br />
<br />
$ speaker-test<br />
<br />
If you do not hear anything, then there is likely a problem with your system configuration.<br />
<br />
=== GPU computing ===<br />
<br />
MATLAB can take advantage of [https://www.mathworks.co.uk/discovery/matlab-gpu.html CUDA enabled GPUs] to speed up applications. In order to take advantage of a supported GPU install the {{Pkg|nvidia}}, {{Pkg|nvidia-utils}}, {{Pkg|ocl-icd}}, {{Pkg|opencl-nvidia}}, and {{Pkg|cuda}} packages. To check if MATLAB is able to utilize the GPU run:<br />
<br />
$ matlab -nodesktop -nosplash -r "x=rand(10, 'single'); g=gpuArray(x); Success=isequal(gather(g), x), exit" | sed -ne '/Success =/,$p'<br />
<br />
=== Install supported compilers ===<br />
<br />
In order to access the full functionality of MATLAB (e.g., to use Simulink, Builder JA, and MEX-file compilation), supported versions of the {{ic|gcc}}, {{ic|g++}}, {{ic|gfortran}}, and {{ic|jdk}} compilers must be installed. Details about the supported compilers for the [https://www.mathworks.com/support/compilers.html current release] and [https://www.mathworks.com/support/sysreq/previous_releases.html previous releases] are available online. Many of the supported {{ic|gcc}}, {{ic|g++}}, {{ic|jdk}} compiler versions for past MATLAB releases are available from the [[AUR]] (e.g., {{AUR|gcc43}}, {{AUR|gcc44}}, {{AUR|gcc47}}, {{AUR|gcc49}}and {{AUR|jdk7}}), while past versions of the {{ic|gfortran}} compilers are not packaged.<br />
<br />
To use previous versions of the {{ic|gcc}}, {{ic|g++}}, and {{ic|gfortran}} compilers with MEX files, edit {{ic|${MATLAB}/bin/mexopts.sh}} and replace all occurrences of {{ic|<nowiki>CC='gcc'</nowiki>}} with {{ic|<nowiki>CC='gcc-4.X'</nowiki>}}, {{ic|<nowiki>CXX='g++'</nowiki>}} with {{ic|<nowiki>CXX='g++-4.X'</nowiki>}}, and {{ic|<nowiki>FC='gfortran'</nowiki>}} with {{ic|<nowiki>FC='gfortran-4.X'</nowiki>}}, where {{ic|X}} is the compiler version appropriate for the particular MATLAB release.<br />
<br />
{{Note|<br />
* Newer versions of Matlab (at least 2017a) does not seem to respect the {{ic|${MATLAB}/bin/mexopts.sh}} customization. Instead it uses {{ic|${MATLAB}/bin/glnxa64/mexopts/LANG_glnxa64.xml}} file.<br />
* Though, it is not officially supported, one could still use higher version of compiler, and ignore the warnings.<br />
}}<br />
<br />
=== Help browser ===<br />
<br />
The help browser uses valuable slots in the dynamic thread vector and causes competition with core functionality provided by libraries like the BLAS that also depend on the dynamic thread vector. The help browser can be configured to use fewer slots in the dynamic thread vector with<br />
<br />
>> webutils.htmlrenderer('basic');<br />
<br />
This is a persistent change and to reverse it use<br />
<br />
>> webutils.htmlrenderer('default');<br />
<br />
=== Serial port access ===<br />
<br />
To successfully connect to any serial port, MATLAB expects to have write access directly to {{ic|/var/lock}} which is not allowed on Arch Linux for security reasons. Instead of allowing this access just for MATLAB, you can work around this problem by redirecting device locking using {{AUR|lockdev-redirect}}. All you have to do is executing MATLAB like this:<br />
<br />
# lockdev-redirect /{MATLAB}/bin/matlab<br />
<br />
If you have created a .desktop file as shortcut to MATLAB, then add "lockdev-redirect" as a prefix to your "Exec=" entry.<br />
<br />
=== HiDPI and 4k ===<br />
<br />
See [[HiDPI#MATLAB]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Warning: Initializing MATLAB Graphics failed ===<br />
<br />
This error seems to happen on multi-monitor setups, see [https://www.mathworks.com/matlabcentral/answers/611786-warning-initializing-matlab-graphics-failed#comment_1131148 this forum post].<br />
<br />
=== Blackscreen in help browser and livescripts ===<br />
<br />
In order to use help browser and livescripts install {{aur|libselinux}}.<br />
<br />
=== Static TLS errors ===<br />
<br />
MATLAB has a number of libraries that have been compiled with static thread local storage (TLS) including the help browser {{ic|doc}} and the BLAS libraries. For example,<br />
<br />
>> doc('help');<br />
>> ones(10)*randn(10);<br />
Error using * <br />
BLAS loading error:<br />
dlopen: cannot load any more object with static TLS<br />
<br />
is related to the bugs:<br />
<br />
* [https://www.mathworks.de/support/bugreports/961964 961964] for which patched libraries are available from [http://www.mathworks.de/support/bugreports/license/accept_license/5730?fname=attachment_961964_12b_13a_13b_14a_glnxa64_2014-01-30.zip&geck_id=961964 MathWorks]{{Dead link|2020|03|30|status=404}}<br />
* [https://www.mathworks.com/support/bugreports/1003952 1003952] for which workarounds exist<br />
<br />
A more general solution of recompiling {{ic|glibc}} has also been suggested. [https://stackoverflow.com/a/19468365]<br />
<br />
=== Blank/grey UI when using WM (non-reparenting window manager) ===<br />
<br />
See [[Java#Gray window, applications not resizing with WM, menus immediately closing]].<br />
<br />
=== Corrupted text and fonts in menus and fields ===<br />
<br />
If you notice that the menus or the input fields are corrupted or not appearing correctly then you can try to activate the ''"'''Use antialiasing to smooth desktop fonts'''"'' option in Matlab preferences, it seems to solve the problem. Go to '''''Preferences -> Matlab -> Fonts''''' and activate it. You will need to restart Matlab in order to take affect.<br />
<br />
=== Installation dependencies missing ===<br />
<br />
Matlab might complain that it cannot find a package. Look at the package name and install it with [[Pacman]], or in the case of x86_64 there are some libraries only in [[AUR]]. {{AUR|matlab}} and {{AUR|matlab-dummy}} packages contain a list of up-to-date dependencies for the newest Matlab version.<br />
<br />
See also [[#Unable to launch the MATLABWindow application]].<br />
<br />
=== Installation error: archive is not a ZIP archive ===<br />
<br />
During the installation you can get:<br />
<br />
The following error was detected while installing ''package_name'': archive is not a ZIP archive <br />
Would you like to retry installing ''package_name''? If you press No, the installer will exit without completing the installation. More information can be found at /tmp/mathworks_root.log<br />
<br />
Matlab downloads all packages to {{ic|/tmp/}} directory which resides in RAM and is maximum size of half of available memory. In this case it is not enough for installation files and Matlab 2019a installer will warn you about this. If it did not, or if you ignored the warning, you will have got the above error.<br />
<br />
You can either [[Tmpfs#Examples|resize tmpfs]] (3,5 GB is not enough, 6 GB works), or remove packages from base install and add them later with built-in Matlab add-on installer.<br />
<br />
=== Install-time library errors ===<br />
<br />
* Make sure that the symlink {{ic|bin/glnx64/libstdc++.so.6}} is pointing to the correct version of {{ic|libstdc++.so.xx}} (which is also in the same directory and has numbers where 'xx' is). By default, it may be pointing to an older (and nonexistent) version (different value for 'xx').<br />
<br />
* Make sure the device you are installing from is not mounted as {{ic|noexec}}<br />
<br />
* If you downloaded the files from Mathworks' website, make sure they are not on an NTFS or FAT partition, because that can mess up the symlinks. Ext4 or Ext3 should work.<br />
<br />
=== Hangs on rendering or exiting with Intel graphics ===<br />
<br />
Some users have reported issues with DRI3 enabled on Intel Graphics chips. A possible workaround is to disable DRI3 and run MATLAB with hardware rendering on DRI2; to do so, launch MATLAB with the environment variable LIBGL_DRI3_DISABLE set to 1:<br />
<br />
LIBGL_DRI3_DISABLE=1 /{MATLAB}/bin/matlab<br />
<br />
If the previous workaround does not work, the issue can be circumvented by selecting software rendering with the MATLAB command (beware, performance may be very poor when doing e.g. big or complex 3D plots):<br />
<br />
opengl('save','software')<br />
<br />
See [https://bugzilla.redhat.com/show_bug.cgi?id=1357571] and [https://bugs.freedesktop.org/show_bug.cgi?id=96671] for more.<br />
<br />
=== LiveScript errors ===<br />
<br />
If you get the error when attempting to load or create a LiveScript:<br />
{{ic|Viewing matlab live script files is not currently supported by this operating system configuration}}<br />
*It could be because of broken symlinks of {{Pkg|libgcrypt}} and other dependencies, after system updates. On the first start of the Live Editor the components are extracted and these libary symlinks are created (if not existing).<br />
: A solution is to simply delete the whole folder containing the broken symlinks and the extracted components, which are in the installation directory:<br />
''matlab_root''/sys/jxbrowser-chromium<br />
: Or, if the installation directory is not user writable, then in:<br />
~/.matlab/R2017b/HtmlPanel<br />
: Matlab will then regenerate the contents on the next Live Editor start.<br />
: A better option is to replace libgcrypt symlink in this extraction directory with a less precise one. For example, after extraction, this link to /lib64/libgcrypt.so.20.2.4 is created. Replace it with e.g. /lib64/libgcrypt.so.20.<br />
: Matlab R2020 does not contain a chromium directory anymore. Relinking the library file libcrypto.so.1.1 with the system file can resolve the issue. It is located in:<br />
''matlab_root''/bin/glnxa64<br />
*Also the steps in [[#Unable to launch the MATLABWindow application]] may resolve the issue.<br />
*It can also happen due to missing gconf package. Make sure {{AUR|gconf}} is installed.<br />
*If the above does not help, execute in the command window<br />
>> com.mathworks.mde.liveeditor.widget.rtc.CachedLightweightBrowserFactory.createLightweightBrowser()<br />
to get a more detailed error message.<br />
* A debugging console can be opened with<br />
>> com.mathworks.mde.webbrowser.HtmlPanelDebugConsole.invoke;<br />
<br />
=== Using webcam/video device ===<br />
<br />
Make sure the correct support package add-ons are installed (webcam or OS Generic Video Interface for example). If running matlab as a user, make sure your user has write permissions to wherever the support packages are being downloaded and installed.<br />
<br />
Since MATLAB R2017a, Image Acqusition Toolbox is using GStreamer library version 1.0. It previously used version 0.10.<br />
<br />
In general, USB Webcam Support Package does a better job working with UVC and built-in cameras than OS Generic Video Interface Support Package.<br />
<br />
=== MATLAB hangs for several minutes when closing Help Browser ===<br />
<br />
{{Style|Written in first person}}<br />
<br />
Since upgrade of glibc from 2.24 to 2.25, MATLAB (at least R2017a) hangs when closing Help Browser. The issue is related to the particular version of jxbrowser-chromium shipped with MATLAB.<br />
This issue is still present with glibc 2.26 and MATLAB R2017b and R2018a.<br />
<br />
To fix this issue, download the [https://www.teamdev.com/jxbrowser latest jxbrowser] and replace the following jars from MATLAB:<br />
<br />
''matlab_root''/java/jarext/jxbrowser-chromium/jxbrowser-chromium.jar<br />
''matlab_root''/java/jarext/jxbrowser-chromium/jxbrowser-linux64.jar<br />
<br />
MATLAB should automatically unpack those jars into {{ic|''matlab_root''/sys/jxbrowser-chromium/glnxa64/chromium}} when first opening Help Browser.<br />
Remove {{ic|''matlab_root''/sys/jxbrowser-chromium/glnxa64/chromium}} directory to make sure MATLAB uses the latest jxbrowser.<br />
<br />
Unfortunately, this workaround does not work in R2017b anymore. Going deeper into investigation of this issue, it is related to a crash of one of jxbrowser-chromium processes. The parent process of jxbrowser-chromium then sits there and waits for response from a process that is already dead. This causes MATLAB main window to freeze. You can easily unfreeze MATLAB by manually killing all leftover jxbrowser-chromium processes.<br />
<br />
I have come up with this simple script that uses inotify and waits for user to close Help browser in MATLAB. It triggers when user closes Help browser and sends kill signal to all leftover jxbrowser-chromium processes:<br />
<br />
{{bc|1=<br />
#!/bin/sh<br />
<br />
if [ -z "$1" ]; then<br />
REL=R2017b<br />
else<br />
REL=$1<br />
fi<br />
<br />
JXPATH="/path/to/MATLAB/$REL/sys/jxbrowser-chromium/glnxa64/chromium"<br />
CMD="inotifywait -m -e CLOSE $JXPATH/resources.pak"<br />
<br />
#Exit if the daemon is already active<br />
if ! pgrep -f "$CMD" > /dev/null; then<br />
#Wait for user to close Help Browser, then killall leftover jxbrowser processes<br />
$CMD {{!}}<br />
while read line<br />
do<br />
killall "$JXPATH/jxbrowser-chromium"<br />
done<br />
else<br />
exit<br />
fi<br />
}}<br />
<br />
I run this script as part of my MATLAB start script like that:<br />
~/bin/unfreeze_matlab.sh R2017b &<br />
<br />
To make sure that this background job is killed when I exit MATLAB, I use this in the beginning of MATLAB start script:<br />
trap "trap - SIGTERM && kill -- -$$" SIGINT SIGTERM EXIT<br />
<br />
=== Some dropdown menus cannot be selected ===<br />
<br />
In some interfaces - such as Simulation Data Inspector or Simulink Test Manager - nothing happens when choosing an item in dropdown menu (for example, when trying to change a number of subplots in Simulation Data Inspector). To work around this issue, hold down the Shift key while clicking the item in dropdown menu.<br />
<br />
=== Not starting - licensing error ===<br />
<br />
In case MATLAB will not start from a [[desktop environment]] by the call of its [[desktop file]] one should see the output as you start it from the terminal.<br />
<br />
For a ''Licensing error'' such as:<br />
<br />
{{hc|# matlab|<nowiki><br />
MATLAB is selecting SOFTWARE OPENGL rendering.<br />
License checkout failed.<br />
License Manager Error -9<br />
This error may occur when: <br />
-The hostid of this computer does not match the hostid in the license file. <br />
-A Designated Computer installation is in use by another user. <br />
If no other user is currently running MATLAB, you may need to activate.<br />
<br />
Troubleshoot this issue by visiting: <br />
https://www.mathworks.com/support/lme/R2017a/9<br />
<br />
Diagnostic Information:<br />
Feature: MATLAB <br />
License path: /home/<USER>/.matlab/R2017a_licenses/license_<NUM>_R2017a.lic:/home/<USER>/.matlab/R2017a_licenses/lice<br />
nse_Darkness_<NUM>_R2017a.lic:/opt/MATLAB/R2017a/licenses/license.dat:/opt/MATLAB/R2017a/licenses/*<br />
.lic <br />
Licensing error: -9,57.<br />
</nowiki>}}<br />
<br />
A re-activation might solve the problem.<br />
<br />
/usr/local/MATLAB/R2017a/bin/activate_matlab.sh -javadir /usr/lib/jvm/java-8-openjdk/jre/<br />
<br />
=== MATLAB crashes with "Failure loading desktop class" on startup ===<br />
<br />
In case MATLAB will not start and starting it from command line gives you the following error:<br />
{{hc<br />
|$ matlab|<br />
Fatal Internal Error: Internal Error: Failure occurs during desktop startup. Details: Failure loading desktop class.<br />
}}<br />
and you have the option [[Java#GTK LookAndFeel|-Dswing.defaultlaf=com.sun.java.swing.plaf.gtk.GTKLookAndFeel]] set in your {{ic|_JAVA_OPTIONS}} environment variable, start MATLAB with<br />
<br />
$ _JAVA_OPTIONS= matlab<br />
<br />
If this works, add the line<br />
<br />
export _JAVA_OPTIONS=<br />
<br />
to your MATLAB launcher script. Optionally re-add other Java options.<br />
<br />
=== Unable to type in text fields of interfaces based on MATLABWindow ===<br />
<br />
{{Style|Written in first person}}<br />
Since R2018a, it is not possible to type text in interfaces based on MATLABWindow - like Signal Editor, Add-Ons Explorer and others.<br />
MATLABWindow and MATLAB's webwindow infrastructure is based on Chromium Embedded Framework, and it looks like a known and long standing bug: https://bitbucket.org/chromiumembedded/cef/issues/2026/multiple-major-keyboard-focus-issues-on<br />
<br />
One possible workaround is to switch focus from the MATLABWindow to another window and then switch back - so that you can type.<br />
<br />
To elaborate more on this workaround (since the problem is still there in R2018b), here is what i did in my Openbox config (note that the A-Middle keybinding already exist in default config):<br />
<br />
<mousebind button="A-Middle" action="Press"><br />
<action name="Unfocus"/><br />
<action name="Focus"/><br />
</mousebind><br />
<br />
Now, whenever it is not possible to type in a text field, I press Alt+Mouse middle mouse and then I can type again.<br />
<br />
This problem is critical during installation. After one clicks some elements in the installation window, he will not be able to type into any textbox anymore and switching between windows does not always work. To circumvent the issue, one shall only use key-press, instead of mouse click during installation. MATLAB installer has a poor support on Wayland, one may also consider using other WM instead during installation.<br />
<br />
=== Unable to launch the MATLABWindow application ===<br />
<br />
In MATLAB versions R2018b until R2022b, the installer crashes as follows:<br />
<br />
{{hc<br />
| $ ./install |<br />
terminate called after throwing an instance of 'std::runtime_error'<br />
what(): Failed to launch web window with error: Unable to launch the MATLABWindow application. The exit code was: 127<br />
[1] 1409378 IOT instruction (core dumped) ./install<br />
}}<br />
<br />
To find out why {{ic|MATLABWindow}} is crashing, run it manually to get detailed information.<br />
<br />
{{hc<br />
| $ ./bin/glnxa64/MATLABWindow |<br />
bin/glnxa64/MATLABWindow: symbol lookup error: /usr/lib/libcairo.so.2: undefined symbol: FT_Get_Color_Glyph_Layer<br />
}}<br />
<br />
{{ic|FT_Get_Color_Glyph_Layer}} is a symbol of {{Pkg|freetype2}}, which indicates a library incompatibility between the MATLAB application and the Arch Linux packages. [https://ww2.mathworks.cn/matlabcentral/answers/364551-why-is-matlab-unable-to-run-the-matlabwindow-application-on-linux]<br />
<br />
To fix this, put aside MATLAB's {{ic|libfreetype.so*}}.<br />
<br />
$ rm ./bin/glnxa64/libfreetype.so*<br />
<br />
You can also use {{ic|LD_PRELOAD}} environment variable to force MATLAB use Arch Linux's libfreetype without removing the lib file.<br />
<br />
$ export LD_PRELOAD=/lib64/libfreetype.so<br />
$ ./install<br />
<br />
Similarly, if the error is caused by {{ic|undefined symbol: g_log_structured...}}, put aside MATLAB's {{ic|libglib-2.0.so*}}. If the error is caused by {{ic|path to/libstdc++.so.6: version `CXXABI_1.3.9' not found (required by _somelibrary_)}}, put aside MATLAB's {{ic|libstdc++.so.6}}.<br />
<br />
=== Cannot verify university login during installation ===<br />
<br />
For total headcount license users, MATLAB will pop-up a window asking the user to login with their credentials in a web browser. However, if run with {{ic|sudo}}, most browsers (especially chromium) will not run. To circumvent this problem, one shall 'active the computer' through MATLAB's website using a browser by a normal user. [https://www.mathworks.com/matlabcentral/answers/326647-verify-university-login-not-open-browser See this issue]<br />
<br />
=== Missing libcrypt.so.1 ===<br />
<br />
If you get this error when launching or installing MATLAB (R2020a and later), install {{Pkg|libxcrypt-compat}}.<br />
<br />
=== Running installer as root does not launch the GUI ===<br />
<br />
If you run the installer as root and the GUI does not appear (but does appear without launching as root), try temporarily allowing the root user to access the X Server by running the following commands in order (where {{ic|./install}} is the command to run the installer as root):<br />
<br />
$ xhost +SI:localuser:root<br />
# ./install<br />
$ xhost -SI:localuser:root<br />
<br />
Note that the last command should be executed upon finishing the installation process, and {{ic|localuser}} is a string literal. See [https://au.mathworks.com/matlabcentral/answers/1461039-on-ubuntu-sudo-won-t-run-the-install-file#comment_1782671 this support answer], and {{man|1|xhost}}.<br />
<br />
In addition, verify that the {{ic|DISPLAY}} environment variable is set.<br />
<br />
An alternative is to install MATLAB as a local user.<br />
<br />
=== GUI installer is unable to create the target folder when installing as user ===<br />
<br />
Make the folder manually (as root), and take ownership. The path is typically /usr/local/MATLAB<br />
# mkdir -p /path/to/MATLAB/R20XXx<br />
# chown -R $LOGNAME: /path/to/MATLAB/R20XXx<br />
<br />
=== MATLAB crashes when opening Simulink ===<br />
<br />
When running from terminal the error message is:<br />
<br />
Inconsistency detected by ld.so: ../elf/dl-tls.c: 597: _dl_allocate_tls_init: Assertion `listp != NULL' failed!<br />
<br />
See upstream bug report here: https://www.mathworks.com/support/bugreports/details/2632298<br />
<br />
=== MATLAB cannot open or create script files ===<br />
<br />
See [[#Unable to launch the MATLABWindow application]].<br />
<br />
=== Calls to mex fail ===<br />
<br />
If calls from MATLAB or Simulink to mex (e.g. rapid accelerator) fail with the error {{ic|*.mexa64 is not a MEX file}}, even though the resulting file is usable, it may help to edit {{ic|}} in either {{ic|matlab/bin/}} or {{ic|~/.matlab7rc.sh}} by changing the {{ic|LDPATH_PREFIX}} variable from its empty default: [https://github.com/alecjacobson/matlab/blob/883d417a99fcb8ead89387cee243e51a92864019/bin/.matlab7rc.sh#L170]<br />
<br />
{{hc|matlab/bin/.matlab7rc.sh (or ~/.matlab7rc.sh)|2=<br />
...<br />
case "$ARCH" in<br />
'''glnx*)''' # Make sure you are modifying case '''glnx*'''<br />
AUTOMOUNT_MAP=<nowiki>''</nowiki><br />
DISPLAY="$DISPLAY"<br />
ARCH="$ARCH"<br />
TOOLBOX="$TOOLBOX"<br />
MATLABPATH="$MATLABPATH"<br />
SHELL="$SHELL"<br />
'''LDPATH_PREFIX='/usr/lib' '''<br />
...<br />
}}<br />
<br />
=== Incompatibilities with some python libraries using MKL ===<br />
<br />
Some python code running inside matlab may fail with an error mentioning {{ic|Parameter * was incorrect on entry to }}. This can be avoided by calling<br />
py.sys.setdlopenflags(int32(bitor(int64(py.os.RTLD_NOW), int64(py.os.RTLD_DEEPBIND))));<br />
or<br />
py.sys.setdlopenflags(int32(bitor(int64(py.os.RTLD_LAZY), int64(py.os.RTLD_DEEPBIND))));<br />
directly before any calls to {{ic|py}} and after calls to {{ic|pyenv}}.<br />
See [https://www.mathworks.com/matlabcentral/answers/358233-matlab-python-interface-broken?s_tid=email_ans_new_ans_ans_h#answer_283353 this support answer].<br />
<br />
=== Settings not persisting between MATLAB restarts ===<br />
<br />
In some cases on recent Arch systems matlab is unable to export {{ic|.mlsettings}} files, preventing toolbox and some matlab settings from being saved to disk and persisted. These cases come from matlab trying to hard link new files from {{ic|/tmp}} directly to the preferences directory (usually {{ic|~/.matlab/release}} where {{ic|release}} is the matlab version, e.g. {{ic|R2021b}}). As a workaround, run matlab with the {{ic|$TMPDIR}} environment variable set to a folder on the same file system as the preferences directory. [https://www.mathworks.com/matlabcentral/answers/1777865-matlab-preferences-not-being-saved-across-sessions]<br />
<br />
=== "Unable to open this file in the current system configuration" ===<br />
<br />
The error can be fixed by setting aside the l{{ic|ibfreetype.so.6}} in {{ic|''matlab_root''/bin/glnxa64/}}. You may run the following command:<br />
<br />
cd ''matlab_root''/bin/glnxa64/<br />
mv libfreetype.so.6 libfreetype.so.6.old<br />
<br />
=== Symbols in toolstrip menus are not diplayed properly ===<br />
<br />
{{Expansion|Explain which symbols are needed, so that users can choose any font providing them.}}<br />
<br />
This issue can be fixed by [[install]]ing {{Pkg|noto-fonts}}.<br />
<br />
=== Blank screen on Xwayland ===<br />
As suggested in [[Wayland#Java]], this issue can be fixed by adding in the Matlab launcher script:<br />
export _JAVA_AWT_WM_NONREPARENTING=1<br />
<br />
== MATLAB in a systemd-nspawn ==<br />
<br />
MATLAB can be run within a systemd-nspawn container to maintain a static system and avoid the library issues that often plague matlab installs after significant updates to libraries in Arch. Refer to [[Systemd-nspawn]] for detailed information on setting up such containers.<br />
<br />
The following instruction is to get a MATLAB R2021b installation running in a minimal Debian 11 environment. It assumes MATLAB is already installed as normal in "/usr/local/MATLAB/R2021b".<br />
<br />
Use [[Xhost]] to allow the nspawn environment to use the existing X server instance, see also [[Systemd-nspawn#Use an X environment]].<br />
<br />
Create a minimal Debian environment in a directory ("deb11" here) with:<br />
<br />
$ debootstrap --include=systemd-container --components=main,contrib bullseye deb11<br />
<br />
Set a password for the root user and create regular user:<br />
<br />
$ systemd-nspawn -D deb11<br />
passwd<br />
useradd -m username<br />
logout<br />
<br />
and then boot the environment with:<br />
<br />
$ systemd-nspawn --bind-ro=/dev/dri --bind-ro=/tmp/.X11-unix --bind=/dev/shm --bind=/usr/local/MATLAB --setenv=DISPLAY=:0 --setenv=MESA_LOADER_DRIVER_OVERRIDE=i965 -b -D deb11<br />
<br />
Install the following packages to have the required libraries in the nspawn environment for MATLAB: https://github.com/mathworks-ref-arch/container-images/blob/master/matlab-deps/r2021b/ubuntu20.04/Dockerfile<br />
<br />
"mesa-utils" and dependencies needs to be installed to support graphics acceleration.<br />
"usbutils" can be installed to support usb interfaces for I/O with MATLAB.<br />
<br />
Install the matlab-support (from contrib source) package in the environment for some convenient integration. <br />
<br />
$ apt-get install matlab-support<br />
<br />
MATLAB can be launched from within the environment normally by using the binary at {{ic|''matlab_root''/bin}}.<br />
<br />
Another way is to add something like <br />
-u username -a /usr/local/MATLAB/R2021b/bin/matlab -nosoftwareopengl -useStartupFolderPref<br />
<br />
to the systemd-nspawn command above.</div>Ondrianhttps://wiki.archlinux.org/index.php?title=NVIDIA&diff=654408NVIDIA2021-03-10T13:45:45Z<p>Ondrian: /* DRM kernel mode setting */ add example</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X server]]<br />
[[cs:NVIDIA]]<br />
[[de:Nvidia]]<br />
[[es:NVIDIA]]<br />
[[fa:اِنویدیا]]<br />
[[fr:Nvidia]]<br />
[[it:NVIDIA]]<br />
[[ja:NVIDIA]]<br />
[[nl:NVIDIA]]<br />
[[ru:NVIDIA]]<br />
[[zh-hans:NVIDIA]]<br />
{{Related articles start}}<br />
{{Related|NVIDIA/Tips and tricks}}<br />
{{Related|NVIDIA/Troubleshooting}}<br />
{{Related|Nouveau}}<br />
{{Related|NVIDIA Optimus}}<br />
{{Related|PRIME}}<br />
{{Related|Bumblebee}}<br />
{{Related|nvidia-xrun}}<br />
{{Related|Xorg}}<br />
{{Related|Vulkan}}<br />
{{Related articles end}}<br />
<br />
This article covers the proprietary [http://www.nvidia.com NVIDIA] graphics card driver. For the open-source driver, see [[Nouveau]]. If you have a laptop with hybrid Intel/NVIDIA graphics, see [[NVIDIA Optimus]] instead.<br />
<br />
== Installation ==<br />
<br />
{{Warning|Avoid installing the NVIDIA driver through the package provided from the NVIDIA website. Installation through [[pacman]] allows upgrading the driver together with the rest of the system.}}<br />
<br />
These instructions are for those using the stock {{Pkg|linux}} or {{Pkg|linux-lts}} packages. For custom kernel setup, skip to the [[#Custom kernel|next]] subsection.<br />
<br />
1. If you do not know what graphics card you have, find out by issuing:<br />
:{{bc|<nowiki>$ lspci -k | grep -A 2 -E "(VGA|3D)"</nowiki>}}<br />
<br />
2. Determine the necessary driver version for your card by:<br />
:* finding the code name (e.g. NV50, NVC0, etc.) on [https://nouveau.freedesktop.org/wiki/CodeNames/ Nouveau wiki's code names page] or [https://gitlab.freedesktop.org/nouveau/wiki/-/blob/master/sources/CodeNames.mdwn]<br />
:* looking up the name in NVIDIA's [https://www.nvidia.com/object/IO_32667.html legacy card list]: if your card is not there you can use the latest driver<br />
:* visiting NVIDIA's [https://www.nvidia.com/Download/index.aspx driver download site]<br />
<br />
3. Install the appropriate driver for your card:<br />
:* For GeForce 630-900, 10-20, and Quadro/Tesla/Tegra K-series cards and newer [NVE0, NV110 and newer family cards from around 2010 and later], [[install]] the {{Pkg|nvidia}} package (for use with the {{Pkg|linux}} kernel) or {{Pkg|nvidia-lts}} (for use with the {{Pkg|linux-lts}} kernel) package.<br />
::* If these packages do not work, {{AUR|nvidia-beta}} may have a newer driver version that offers support.<br />
:* For GeForce 400/500/600 series cards [NVCx and NVDx] from around 2010-2011, [[install]] the {{AUR|nvidia-390xx-dkms}} package.<br />
<br />
:* For even older cards (released in 2010 or earlier), have a look at [[#Unsupported drivers]].<br />
<br />
4. For 32-bit application support, also install the corresponding ''lib32'' nvidia package from the [[multilib]] repository (e.g. {{Pkg|lib32-nvidia-utils}}).<br />
<br />
5. Reboot. The {{Pkg|nvidia}} package contains a file which blacklists the ''nouveau'' module, so rebooting is necessary.<br />
<br />
Once the driver has been installed, continue to [[#Xorg configuration]].<br />
<br />
=== Unsupported drivers ===<br />
<br />
If you have a GeForce 300 series card or older (released in 2010 or earlier), Nvidia no longer supports drivers for your card. This means that these drivers [https://nvidia.custhelp.com/app/answers/detail/a_id/3142/ do not support the current Xorg version]. It thus might be easier if you use the [[Nouveau]] driver, which supports the old cards with the current Xorg.<br />
<br />
However, Nvidia's legacy drivers are still available and might provide better 3D performance/stability.<br />
<br />
* For GeForce 8/9, ION and 100-300 series cards [NV5x, NV8x, NV9x and NVAx], [[install]] the {{AUR|nvidia-340xx-dkms}} package.<br />
* GeForce 7 series cards and older [NV6x, NV4x and lower] do not have a driver packaged for Arch Linux.<br />
<br />
=== Custom kernel ===<br />
<br />
If you are using a custom kernel, compilation of the Nvidia kernel modules can be automated with [[DKMS]].<br />
<br />
Install the {{Pkg|nvidia-dkms}} package (or a specific branch). The Nvidia module will be rebuilt after every Nvidia or kernel update thanks to the DKMS [[pacman hook]].<br />
<br />
=== DRM kernel mode setting ===<br />
<br />
{{Pkg|nvidia}} 364.16 adds support for DRM (Direct Rendering Manager) [[kernel mode setting]]. To enable this feature, add the {{ic|1=nvidia-drm.modeset=1}} [[kernel parameter]]. For basic functionality that should suffice, if you want to ensure it's loaded at the earliest possible occasion, or are noticing startup issues (such as the nvidia kernel module being loaded after the [[Display manager]]) you can add {{ic|nvidia}}, {{ic|nvidia_modeset}}, {{ic|nvidia_uvm}} and {{ic|nvidia_drm}} to the initramfs according to [[Mkinitcpio#MODULES]].<br />
<br />
If added to the initramfs do not forget to run [[mkinitcpio]] every time there is a {{Pkg|nvidia}} driver update. See [[#Pacman hook]] to automate these steps.<br />
<br />
{{Warning|1=Enabling [[KMS]] causes [[GNOME]] to default to [[Wayland]]. Non-Wayland-native applications suffer from poor performance in Wayland sessions because of the lack of hardware accelerated XWayland. This is [https://www.phoronix.com/scan.php?page=news_item&px=NVIDIA-GL-VLK-XWayland expected to be resolved "soon"], but there is no committed timeline from NVIDIA. Use the ''GNOME on Xorg'' session instead.}}<br />
<br />
{{Note|1=The NVIDIA driver does '''not''' provide an {{ic|fbdev}} driver for the high-resolution console for the kernel compiled-in {{ic|vesafb}} module. However, the kernel compiled-in {{ic|efifb}} module supports a high-resolution console on EFI systems. This method requires GRUB or rEFInd and is described in [[NVIDIA/Tips and tricks#Fixing terminal resolution]].[https://forums.fedoraforum.org/showthread.php?t=306271][https://www.reddit.com/r/archlinux/comments/4gwukx/nvidia_drivers_and_high_resolution_tty_possible/][https://www.reddit.com/r/archlinux/comments/86lqc5/tty_resolution_nvidia_psaish/].}}<br />
<br />
==== Pacman hook ====<br />
<br />
To avoid the possibility of forgetting to update [[initramfs]] after an NVIDIA driver upgrade, you may want to use a [[pacman hook]]:<br />
<br />
{{hc|/etc/pacman.d/hooks/nvidia.hook|2=<br />
[Trigger]<br />
Operation=Install<br />
Operation=Upgrade<br />
Operation=Remove<br />
Type=Package<br />
Target=nvidia<br />
Target=linux<br />
# Change the linux part above and in the Exec line if a different kernel is used<br />
<br />
[Action]<br />
Description=Update Nvidia module in initcpio<br />
Depends=mkinitcpio<br />
When=PostTransaction<br />
NeedsTargets<br />
Exec=/bin/sh -c 'while read -r trg; do case $trg in linux) exit 0; esac; done; /usr/bin/mkinitcpio -P'}}<br />
<br />
Make sure the {{ic|Target}} package set in this hook is the one you've installed in steps above (e.g. {{ic|nvidia}}, {{ic|nvidia-dkms}}, {{ic|nvidia-lts}} or {{ic|nvidia-ck-something}}).<br />
<br />
{{Note|The complication in the {{ic|Exec}} line above is in order to avoid running {{ic|mkinitcpio}} multiple times if both {{ic|nvidia}} and {{ic|linux}} get updated. In case this doesn't bother you, the {{ic|1=Target=linux}} and {{ic|NeedsTargets}} lines may be dropped, and the {{ic|Exec}} line may be reduced to simply {{ic|1=Exec=/usr/bin/mkinitcpio -P}}.}}<br />
<br />
=== Hardware accelerated video decoding ===<br />
<br />
Accelerated video decoding with VDPAU is supported on GeForce 8 series cards and newer. Accelerated video decoding with NVDEC is supported on Fermi (~400 series) cards and newer. See [[hardware video acceleration]] for details.<br />
<br />
== Xorg configuration ==<br />
<br />
The proprietary NVIDIA graphics card driver does not need any Xorg server configuration file. You can [[Xorg#Running|start X]] to see if the Xorg server will function correctly without a configuration file. However, it may be required to create a configuration file (prefer {{ic|/etc/X11/xorg.conf.d/20-nvidia.conf}} over {{ic|/etc/X11/xorg.conf}}) in order to adjust various settings. This configuration can be generated by the NVIDIA Xorg configuration tool, or it can be created manually. If created manually, it can be a minimal configuration (in the sense that it will only pass the basic options to the [[Xorg]] server), or it can include a number of settings that can bypass Xorg's auto-discovered or pre-configured options.<br />
<br />
{{Tip|For more configuration options, see [[NVIDIA/Troubleshooting]].}}<br />
<br />
=== Automatic configuration ===<br />
<br />
The NVIDIA package includes an automatic configuration tool to create an Xorg server configuration file ({{ic|xorg.conf}}) and can be run by:<br />
# nvidia-xconfig<br />
<br />
This command will auto-detect and create (or edit, if already present) the {{ic|/etc/X11/xorg.conf}} configuration according to present hardware.<br />
<br />
If there are instances of DRI, ensure they are commented out:<br />
# Load "dri"<br />
Double check your {{ic|/etc/X11/xorg.conf}} to make sure your default depth, horizontal sync, vertical refresh, and resolutions are acceptable.<br />
<br />
=== nvidia-settings ===<br />
<br />
The {{Pkg|nvidia-settings}} tool lets you configure many options using either CLI or GUI. Running {{ic|nvidia-settings}} without any options launches the GUI, for CLI options see {{man|1|nvidia-settings}}.<br />
<br />
You can run the CLI/GUI as a non-root user and save the settings to {{ic|~/.nvidia-settings-rc}} or save it as [[Xorg#Using_xorg.conf|xorg.conf]] by using the option ''Save to X configuration File'' for a multi-user environment.<br />
<br />
To load the {{ic|~/.nvidia-settings-rc}} for the current user:<br />
<br />
$ nvidia-settings --load-config-only<br />
<br />
See [[Autostarting]] to start this command on every boot.<br />
<br />
{{Note|[[Xorg]] may not start or crash on startup after saving {{ic|nvidia-settings}} changes. Adjusting or deleting the generated {{ic|~/.nvidia-settings-rc}} and/or [[Xorg]] file(s) should recover normal startup.}}<br />
<br />
=== Manual configuration ===<br />
<br />
Several tweaks (which cannot be enabled [[#Automatic configuration|automatically]] or with [[#nvidia-settings|nvidia-settings]]) can be performed by editing your configuration file. The Xorg server will need to be restarted before any changes are applied.<br />
<br />
See [https://download.nvidia.com/XFree86/Linux-x86_64/450.80.02/README/index.html NVIDIA Accelerated Linux Graphics Driver README and Installation Guide] for additional details and options.<br />
<br />
==== Minimal configuration ====<br />
<br />
A basic configuration block in {{ic|20-nvidia.conf}} (or deprecated in {{ic|xorg.conf}}) would look like this:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-nvidia.conf|<br />
Section "Device"<br />
Identifier "Nvidia Card"<br />
Driver "nvidia"<br />
VendorName "NVIDIA Corporation"<br />
BoardName "GeForce GTX 1050 Ti"<br />
EndSection<br />
}}<br />
<br />
==== Disabling the logo on startup ====<br />
<br />
Add the {{ic|"NoLogo"}} option under section {{ic|Device}}:<br />
Option "NoLogo" "1"<br />
<br />
==== Overriding monitor detection ====<br />
<br />
The {{ic|"ConnectedMonitor"}} option under section {{ic|Device}} allows to override monitor detection when X server starts, which may save a significant amount of time at start up. The available options are: {{ic|"CRT"}} for analog connections, {{ic|"DFP"}} for digital monitors and {{ic|"TV"}} for televisions.<br />
<br />
The following statement forces the NVIDIA driver to bypass startup checks and recognize the monitor as DFP:<br />
Option "ConnectedMonitor" "DFP"<br />
{{Note| Use "CRT" for all analog 15 pin VGA connections, even if the display is a flat panel. "DFP" is intended for DVI, HDMI, or DisplayPort digital connections only.}}<br />
<br />
==== Enabling brightness control ====<br />
<br />
Add under section {{ic|Device}}:<br />
Option "RegistryDwords" "EnableBrightnessControl=1"<br />
<br />
If brightness control still does not work with this option, try installing {{AUR|nvidia-bl}}.<br />
<br />
{{Note|Installing {{AUR|nvidia-bl}} will provide a {{ic|/sys/class/backlight/nvidia_backlight/}} interface to backlight brightness control, but your system may continue to issue backlight control changes on {{ic|/sys/class/backlight/acpi_video0/}}. One solution in this case is to watch for changes on, e.g. {{ic|acpi_video0/brightness}} with ''inotifywait'' and to translate and write to {{ic|nvidia_backlight/brightness}} accordingly. See [[Backlight#sysfs modified but no brightness change]].}}<br />
<br />
==== Enabling SLI ====<br />
<br />
{{Warning|Since the GTX 10xx Series (1080, 1070, 1060, etc) only 2-way SLI is supported. 3-way and 4-way SLI may work for CUDA/OpenCL applications, but will most likely break all OpenGL applications.}}<br />
<br />
Taken from the NVIDIA driver's [ftp://download.nvidia.com/XFree86/Linux-x86/355.11/README/xconfigoptions.html README] Appendix B: ''This option controls the configuration of SLI rendering in supported configurations.'' A "supported configuration" is a computer equipped with an SLI-Certified Motherboard and 2 or 3 SLI-Certified GeForce GPUs.<br />
<br />
Find the first GPU's PCI Bus ID using {{ic|lspci}}:<br />
{{hc|<nowiki>$ lspci | grep VGA</nowiki>|<br />
03:00.0 VGA compatible controller: nVidia Corporation G92 [GeForce 8800 GTS 512] (rev a2)<br />
05:00.0 VGA compatible controller: nVidia Corporation G92 [GeForce 8800 GTS 512] (rev a2)<br />
}}<br />
<br />
Add the BusID (3 in the previous example) under section {{ic|Device}}:<br />
BusID "PCI:3:0:0"<br />
<br />
{{Note|The format is important. The BusID value must be specified as {{ic|"PCI:<BusID>:0:0"}}}}<br />
<br />
Add the desired SLI rendering mode value under section {{ic|Screen}}:<br />
Option "SLI" "AA"<br />
<br />
The following table presents the available rendering modes.<br />
<br />
{| class="wikitable"<br />
! Value !! Behavior<br />
|-<br />
| 0, no, off, false, Single || Use only a single GPU when rendering.<br />
|-<br />
| 1, yes, on, true, Auto || Enable SLI and allow the driver to automatically select the appropriate rendering mode.<br />
|-<br />
| AFR || Enable SLI and use the alternate frame rendering mode.<br />
|-<br />
| SFR || Enable SLI and use the split frame rendering mode.<br />
|-<br />
| AA || Enable SLI and use SLI antialiasing. Use this in conjunction with full scene antialiasing to improve visual quality.<br />
|}<br />
<br />
Alternatively, you can use the {{ic|nvidia-xconfig}} utility to insert these changes into {{ic|xorg.conf}} with a single command:<br />
# nvidia-xconfig --busid=PCI:3:0:0 --sli=AA<br />
<br />
To verify that SLI mode is enabled from a shell:<br />
{{hc|<nowiki>$ nvidia-settings -q all | grep SLIMode</nowiki>|<br />
Attribute 'SLIMode' (arch:0.0): AA <br />
'SLIMode' is a string attribute.<br />
'SLIMode' is a read-only attribute.<br />
'SLIMode' can use the following target types: X Screen.<br />
}}<br />
<br />
{{Warning| After enabling SLI, your system may become frozen/non-responsive upon starting xorg. It is advisable that you disable your display manager before restarting.}}<br />
<br />
{{Tip|If this configuration does not work, you may need to use the PCI Bus ID provided by {{ic|nvidia-settings}},<br />
{{hc|<nowiki>$ nvidia-settings -q all | grep -i pcibus</nowiki>|<br />
Attribute 'PCIBus' (host:0[gpu:0]): 101.<br />
'PCIBus' is an integer attribute.<br />
'PCIBus' is a read-only attribute.<br />
'PCIBus' can use the following target types: GPU, SDI Input Device.<br />
Attribute 'PCIBus' (host:0[gpu:1]): 23.<br />
'PCIBus' is an integer attribute.<br />
'PCIBus' is a read-only attribute.<br />
'PCIBus' can use the following target types: GPU, SDI Input Device.}}<br />
<br />
and comment out the PrimaryGPU option in your xorg.d configuration,<br />
{{hc|/usr/share/X11/xorg.conf.d/10-nvidia-drm-outputclass.conf|<br />
...<br />
<br />
Section "OutputClass"<br />
...<br />
# Option "PrimaryGPU" "yes"<br />
...}}<br />
Using this configuration may also solve any graphical boot issues.<br />
}}<br />
<br />
=== Multiple monitors ===<br />
<br />
See [[Multihead]] for more general information.<br />
<br />
==== Using nvidia-settings ====<br />
<br />
The [[#nvidia-settings|nvidia-settings]] tool can configure multiple monitors.<br />
<br />
For CLI configuration, first get the {{ic|CurrentMetaMode}} by running:<br />
<br />
{{hc|$ nvidia-settings -q CurrentMetaMode|2=<br />
Attribute 'CurrentMetaMode' (hostnmae:0.0): id=50, switchable=no, source=nv-control :: DPY-1: 2880x1620 @2880x1620 +0+0 {ViewPortIn=2880x1620, ViewPortOut=2880x1620+0+0}<br />
}}<br />
<br />
Save everything after the {{ic|::}} to the end of the attribute (in this case: {{ic|1=DPY-1: 2880x1620 @2880x1620 +0+0 {ViewPortIn=2880x1620, ViewPortOut=2880x1620+0+0&#125;}}) and use to reconfigure your displays with {{ic|1=nvidia-settings --assign "CurrentMetaMode=''your_meta_mode''"}}.<br />
<br />
{{Tip|You can create shell aliases for the different monitor and resolution configurations you use.}}<br />
<br />
==== ConnectedMonitor ====<br />
<br />
If the driver does not properly detect a second monitor, you can force it to do so with ConnectedMonitor. <br />
<br />
{{hc|/etc/X11/xorg.conf|<br />
<br />
Section "Monitor"<br />
Identifier "Monitor1"<br />
VendorName "Panasonic"<br />
ModelName "Panasonic MICRON 2100Ex"<br />
HorizSync 30.0 - 121.0 # this monitor has incorrect EDID, hence Option "UseEDIDFreqs" "false"<br />
VertRefresh 50.0 - 160.0<br />
Option "DPMS"<br />
EndSection<br />
<br />
Section "Monitor"<br />
Identifier "Monitor2"<br />
VendorName "Gateway"<br />
ModelName "GatewayVX1120"<br />
HorizSync 30.0 - 121.0<br />
VertRefresh 50.0 - 160.0<br />
Option "DPMS"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Device1"<br />
Driver "nvidia"<br />
Option "NoLogo"<br />
Option "UseEDIDFreqs" "false"<br />
Option "ConnectedMonitor" "CRT,CRT"<br />
VendorName "NVIDIA Corporation"<br />
BoardName "GeForce 6200 LE"<br />
BusID "PCI:3:0:0"<br />
Screen 0<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Device2"<br />
Driver "nvidia"<br />
Option "NoLogo"<br />
Option "UseEDIDFreqs" "false"<br />
Option "ConnectedMonitor" "CRT,CRT"<br />
VendorName "NVIDIA Corporation"<br />
BoardName "GeForce 6200 LE"<br />
BusID "PCI:3:0:0"<br />
Screen 1<br />
EndSection<br />
<br />
}}<br />
<br />
The duplicated device with {{ic|Screen}} is how you get X to use two monitors on one card without {{ic|TwinView}}. Note that {{ic|nvidia-settings}} will strip out any {{ic|ConnectedMonitor}} options you have added.<br />
<br />
==== TwinView ====<br />
<br />
You want only one big screen instead of two. Set the {{ic|TwinView}} argument to {{ic|1}}. This option should be used if you desire compositing. TwinView only works on a per card basis, when all participating monitors are connected to the same card.<br />
Option "TwinView" "1"<br />
<br />
Example configuration:<br />
{{hc|/etc/X11/xorg.conf.d/10-monitor.conf|<br />
Section "ServerLayout"<br />
Identifier "TwinLayout"<br />
Screen 0 "metaScreen" 0 0<br />
EndSection<br />
<br />
Section "Monitor"<br />
Identifier "Monitor0"<br />
Option "Enable" "true"<br />
EndSection<br />
<br />
Section "Monitor"<br />
Identifier "Monitor1"<br />
Option "Enable" "true"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Card0"<br />
Driver "nvidia"<br />
VendorName "NVIDIA Corporation"<br />
<br />
#refer to the link below for more information on each of the following options.<br />
Option "HorizSync" "DFP-0: 28-33; DFP-1: 28-33"<br />
Option "VertRefresh" "DFP-0: 43-73; DFP-1: 43-73"<br />
Option "MetaModes" "1920x1080, 1920x1080"<br />
Option "ConnectedMonitor" "DFP-0, DFP-1"<br />
Option "MetaModeOrientation" "DFP-1 LeftOf DFP-0"<br />
EndSection<br />
<br />
Section "Screen"<br />
Identifier "metaScreen"<br />
Device "Card0"<br />
Monitor "Monitor0"<br />
DefaultDepth 24<br />
Option "TwinView" "True"<br />
SubSection "Display"<br />
Modes "1920x1080"<br />
EndSubSection<br />
EndSection<br />
}}<br />
<br />
[https://download.nvidia.com/XFree86/Linux-x86_64/440.31/README/configtwinview.html Device option information].<br />
<br />
If you have multiple cards that are SLI capable, it is possible to run more than one monitor attached to separate cards (for example: two cards in SLI with one monitor attached to each). The "MetaModes" option in conjunction with SLI Mosaic mode enables this. Below is a configuration which works for the aforementioned example and runs [[GNOME]] flawlessly.<br />
{{hc|/etc/X11/xorg.conf.d/10-monitor.conf|<br />
Section "Device"<br />
Identifier "Card A"<br />
Driver "nvidia"<br />
BusID "PCI:1:00:0"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Card B"<br />
Driver "nvidia"<br />
BusID "PCI:2:00:0"<br />
EndSection<br />
<br />
Section "Monitor"<br />
Identifier "Right Monitor"<br />
EndSection<br />
<br />
Section "Monitor"<br />
Identifier "Left Monitor"<br />
EndSection<br />
<br />
Section "Screen"<br />
Identifier "Right Screen"<br />
Device "Card A"<br />
Monitor "Right Monitor"<br />
DefaultDepth 24<br />
Option "SLI" "Mosaic"<br />
Option "Stereo" "0"<br />
Option "BaseMosaic" "True"<br />
Option "MetaModes" "GPU-0.DFP-0: 1920x1200+4480+0, GPU-1.DFP-0:1920x1200+0+0"<br />
SubSection "Display"<br />
Depth 24<br />
EndSubSection<br />
EndSection<br />
<br />
Section "Screen"<br />
Identifier "Left Screen"<br />
Device "Card B"<br />
Monitor "Left Monitor"<br />
DefaultDepth 24<br />
Option "SLI" "Mosaic"<br />
Option "Stereo" "0"<br />
Option "BaseMosaic" "True"<br />
Option "MetaModes" "GPU-0.DFP-0: 1920x1200+4480+0, GPU-1.DFP-0:1920x1200+0+0"<br />
SubSection "Display"<br />
Depth 24<br />
EndSubSection<br />
EndSection<br />
<br />
Section "ServerLayout"<br />
Identifier "Default"<br />
Screen 0 "Right Screen" 0 0<br />
Option "Xinerama" "0"<br />
EndSection}}<br />
<br />
===== Vertical sync using TwinView =====<br />
<br />
If you are using TwinView and vertical sync (the "Sync to VBlank" option in '''nvidia-settings'''), you will notice that only one screen is being properly synced, unless you have two identical monitors. Although '''nvidia-settings''' does offer an option to change which screen is being synced (the "Sync to this display device" option), this does not always work. A solution is to add the following environment variables at startup, for example append in {{ic|/etc/profile}}:<br />
<br />
export __GL_SYNC_TO_VBLANK=1<br />
export __GL_SYNC_DISPLAY_DEVICE=DFP-0<br />
export VDPAU_NVIDIA_SYNC_DISPLAY_DEVICE=DFP-0<br />
<br />
You can change {{ic|DFP-0}} with your preferred screen ({{ic|DFP-0}} is the DVI port and {{ic|CRT-0}} is the VGA port). You can find the identifier for your display from '''nvidia-settings''' in the "X Server XVideoSettings" section.<br />
<br />
===== Gaming using TwinView =====<br />
<br />
In case you want to play fullscreen games when using TwinView, you will notice that games recognize the two screens as being one big screen. While this is technically correct (the virtual X screen really is the size of your screens combined), you probably do not want to play on both screens at the same time. <br />
<br />
To correct this behavior for SDL, try:<br />
export SDL_VIDEO_FULLSCREEN_HEAD=1<br />
<br />
For OpenGL, add the appropriate Metamodes to your xorg.conf in section {{ic|Device}} and restart X:<br />
Option "Metamodes" "1680x1050,1680x1050; 1280x1024,1280x1024; 1680x1050,NULL; 1280x1024,NULL;"<br />
<br />
Another method that may either work alone or in conjunction with those mentioned above is [[Gaming#Starting_games_in_a_separate_X_server|starting games in a separate X server]].<br />
<br />
==== Mosaic mode ====<br />
<br />
Mosaic mode is the only way to use more than 2 monitors across multiple graphics cards with compositing. Your window manager may or may not recognize the distinction between each monitor. Mosaic mode requires a valid SLI configuration. Even if using Base mode without SLI, the GPUs must still be SLI capable/compatible.<br />
<br />
===== Base Mosaic =====<br />
<br />
Base Mosaic mode works on any set of Geforce 8000 series or higher GPUs. It cannot be enabled from within the nvidia-setting GUI. You must either use the {{ic|nvidia-xconfig}} command line program or edit {{ic|xorg.conf}} by hand. Metamodes must be specified. The following is an example for four DFPs in a 2x2 configuration, each running at 1920x1024, with two DFPs connected to two cards:<br />
$ nvidia-xconfig --base-mosaic --metamodes="GPU-0.DFP-0: 1920x1024+0+0, GPU-0.DFP-1: 1920x1024+1920+0, GPU-1.DFP-0: 1920x1024+0+1024, GPU-1.DFP-1: 1920x1024+1920+1024"<br />
<br />
{{Note|While the documentation lists a 2x2 configuration of monitors, [https://devtalk.nvidia.com/default/topic/579449/linux/basemosaic-v295-vs-v310-vs-v325-only-up-to-three-screens-/post/3954733/#3954733 GeForce cards are artificially limited to 3 monitors] in Base Mosaic mode. Quadro cards support more than 3 monitors. As of September 2014, the Windows driver has dropped this artificial restriction, but it remains in the Linux driver.}}<br />
<br />
===== SLI Mosaic =====<br />
<br />
If you have an SLI configuration and each GPU is a Quadro FX 5800, Quadro Fermi or newer then you can use SLI Mosaic mode. It can be enabled from within the nvidia-settings GUI or from the command line with:<br />
$ nvidia-xconfig --sli=Mosaic --metamodes="GPU-0.DFP-0: 1920x1024+0+0, GPU-0.DFP-1: 1920x1024+1920+0, GPU-1.DFP-0: 1920x1024+0+1024, GPU-1.DFP-1: 1920x1024+1920+1024"<br />
<br />
== Wayland ==<br />
<br />
For now only a few [[Wayland#Compositors|Wayland compositors]] support NVIDIA's buffer API, see [[Wayland#Requirements]] for more information.<br />
<br />
For further configuration options, take a look at the wiki pages or documentation of the respective compositor.<br />
<br />
{{Note | For now XWayland does not support GPU acceleration with the Nvidia proprietary driver, see [[Wayland#XWayland]] for details.}}<br />
<br />
== Tips and tricks ==<br />
<br />
See [[NVIDIA/Tips and tricks]].<br />
<br />
== Troubleshooting ==<br />
<br />
See [[NVIDIA/Troubleshooting]].<br />
<br />
== See also ==<br />
<br />
* [https://forums.developer.nvidia.com/t/current-graphics-driver-releases/28500 Current graphics driver releases in official Nvidia Forum]<br />
* [https://forums.developer.nvidia.com/c/gpu-unix-graphics/linux/148 NVIDIA Developers Forum - Linux Subforum]</div>Ondrianhttps://wiki.archlinux.org/index.php?title=Kernel_mode_setting&diff=654407Kernel mode setting2021-03-10T13:34:45Z<p>Ondrian: /* Early KMS start */ add nvidia kernel modules</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:Kernel]]<br />
[[de:KMS]]<br />
[[es:Kernel mode setting]]<br />
[[fr:KMS]]<br />
[[hu:Kernel mode setting]]<br />
[[ja:Kernel Mode Setting]]<br />
[[ru:Kernel mode setting]]<br />
[[zh-hans:Kernel mode setting]]<br />
[[zh-hant:Kernel mode setting]]<br />
{{Related articles start}}<br />
{{Related|ATI}}<br />
{{Related|Intel graphics}}<br />
{{Related|Nouveau}}<br />
{{Related articles end}}<br />
<br />
{{Expansion|KMS and rootless X (1.16), see [[Talk:Kernel mode setting]] and [[Xorg#Rootless Xorg (v1.16)]].}}<br />
<br />
Kernel [[Wikipedia:Mode-setting|Mode Setting]] (KMS) is a method for setting display resolution and depth in the kernel space rather than user space.<br />
<br />
The Linux kernel's implementation of KMS enables native resolution in the framebuffer and allows for instant console (tty) switching. KMS also enables newer technologies (such as DRI2) which will help reduce artifacts and increase 3D performance, even kernel space power-saving.<br />
<br />
{{Note|The proprietary [[NVIDIA]] driver (since 364.12) also implements kernel mode-setting, but it does not use the built-in kernel implementation and it lacks an fbdev driver for the high-resolution console.}}<br />
<br />
== Background ==<br />
<br />
Previously, setting up the video card was the job of the X server. Because of this, it was not easily possible to have fancy graphics in [[virtual console]]s. Also, each time a switch from X to a virtual console was made ({{ic|Ctrl+Alt+F2}}), the server had to give control over the video card to the kernel, which was slow and caused flickering. The same "painful" process happened when the control was given back to the X server ({{ic|Alt+F7}} when X runs in VT7).<br />
<br />
With Kernel Mode Setting (KMS), the kernel is now able to set the mode of the video card. This makes fancy graphics during bootup, virtual console and X fast switching possible, among other things.<br />
<br />
== Installation ==<br />
<br />
At first, note that for ''any'' method you use, you should ''always'' disable:<br />
<br />
* Any {{ic|<nowiki>vga=</nowiki>}} options in your bootloader as these will conflict with the native resolution enabled by KMS.<br />
* Any {{ic|<nowiki>video=</nowiki>}} lines that enable a framebuffer that conflicts with the driver.<br />
* Any other framebuffer drivers (such as [[uvesafb]]).<br />
<br />
=== Late KMS start===<br />
<br />
[[Intel]], [[Nouveau]], [[ATI]] and [[AMDGPU]] drivers already enable KMS automatically for all chipsets, so you need not install it manually.<br />
<br />
The proprietary [[NVIDIA]] driver supports KMS (since 364.12), which has to be [[NVIDIA#DRM kernel mode setting|manually enabled]].<br />
<br />
The proprietary [[AMD Catalyst]] driver does not support KMS. In order to use KMS you have to replace it with the open-source [[AMDGPU]] or [[ATI]] driver.<br />
<br />
=== Early KMS start ===<br />
<br />
{{Tip|If you encounter problems with the resolution, you can check whether [[#Forcing modes and EDID|enforcing the mode]] helps.}}<br />
<br />
KMS is typically initialized after the [[Arch boot process#initramfs|initramfs stage]]. However it is possible to already enable KMS during the initramfs stage. Add the required module for the [[Xorg#Driver_installation|video driver]] to the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}}:<br />
* {{ic|amdgpu}} for [[AMDGPU]], or {{ic|radeon}} when using the legacy [[ATI]] driver.<br />
* {{ic|i915}} for [[Intel graphics]].<br />
* {{ic|nouveau}} for the open-source [[Nouveau]] driver.<br />
* {{ic|mgag200}} for Matrox graphics.<br />
* Depending on [[QEMU]] graphics in use: {{ic|virtio-gpu}} for VirtIO, {{ic|qxl}} for QXL, or {{ic|cirrus}} for Cirrus.<br />
* {{ic|nvidia nvidia_modeset nvidia_uvm nvidia_drm}} for {{Pkg|nvidia}} driver. See [[NVIDIA#DRM%20kernel%20mode%20setting]] for details.<br />
<br />
For example to enable early KMS for the Intel graphics driver:<br />
{{hc|/etc/mkinitcpio.conf|2=MODULES=(... i915 ...)}}<br />
<br />
{{Note|1=Intel users may need to add {{ic|intel_agp}} before {{ic|i915}} to suppress the ACPI errors (check the output of {{ic|lsmod}} on your running system to see if {{ic|intel_agp}} is loaded). This may be required for resuming from hibernation to work with a changed display configuration. If you use PRIME GPU with Intel IGP being your primary GPU and AMD as the discrete one, adding {{ic|intel_agp}} may lead to troubles when resuming from hibernation (monitor gets no signal). See [https://bbs.archlinux.org/viewtopic.php?id=262043] for details.}}<br />
<br />
If you are using a custom EDID file (not applicable for the built-in resolutions), you should embed it into [[initramfs]] as well:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/usr/lib/firmware/edid/your_edid.bin)<br />
}}<br />
<br />
Then [[regenerate the initramfs]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== My fonts are too tiny ===<br />
<br />
See [[Linux console#Fonts]] for how to change your console font to a large font. The Terminus font ({{Pkg|terminus-font}}) is available in many sizes, such as {{ic|ter-132n}} which is larger.<br />
<br />
Alternatively, [[#Disabling modesetting|disabling modesetting]] might switch to lower resolution and make fonts appear larger.<br />
<br />
=== Problem upon bootloading and dmesg ===<br />
<br />
Polling for connected display devices on older systems can be quite expensive. Poll will happen periodically and can in worst cases take several hundred milliseconds, depending on the hardware. This will cause visible stalls, for example in video playback. These stalls might happen even when your video is on HDP output but you have other non HDP outputs in your hw configuration. If you experience stalls in display output occurring every 10 seconds, disabling polling might help.<br />
<br />
If you see an error code of {{ic|0x00000010 (2)}} while booting up, (you will get about 10 lines of text, the last part denoting that error code), use:<br />
<br />
{{hc|/etc/modprobe.d/modprobe.conf|2=<br />
options drm_kms_helper poll=0<br />
}}<br />
<br />
== Forcing modes and EDID ==<br />
<br />
If your native resolution is not automatically configured or no display at all is detected, then your monitor might send none or just a skewed [[Wikipedia:EDID|EDID]] file. The kernel will try to catch this case and will set one of the most typical resolutions.<br />
<br />
In case you have the EDID file for your monitor you merely need to explicitly enforce it (see below). However most often one does not have direct access to a sane file and it is necessary to either extract an existing one and fix it or to generate a new one.<br />
<br />
Generating new EDID binaries for various resolutions and configurations is possible during kernel compilation by following the [https://www.kernel.org/doc/html/latest/admin-guide/edid.html upstream documentation] (also see [https://www.osadl.org/Single-View.111+M5315d29dd12.0.html here] for a short guide). Other solutions are outlined in details in this [https://kodi.wiki/view/Creating_and_using_edid.bin_via_xorg.conf article]{{Dead link|2020|12|27|status=404}}.<br />
Extracting an existing one is in most cases easier, e.g. if your monitor works fine under Windows you might have luck extracting the EDID from the corresponding driver, or if a similar monitor works which has the same settings you may use {{ic|get-edid}} from the {{Pkg|read-edid}} package. You can also try looking in {{ic|/sys/class/drm/*/edid}}.<br />
<br />
After having prepared your EDID place it in a folder, e.g. called {{ic|edid}} under {{ic|/usr/lib/firmware}} and copy your binary into it.<br />
<br />
To load it at boot, specify the following in the [[kernel command line]]:<br />
<br />
drm.edid_firmware=edid/your_edid.bin<br />
<br />
For kernels older than 4.13, use this line instead:<br />
<br />
drm_kms_helper.edid_firmware=edid/your_edid.bin<br />
<br />
In order to apply it only to a specific connector use:<br />
<br />
drm.edid_firmware=VGA-1:edid/your_edid.bin<br />
<br />
For the built-in resolutions, refer to the table below. The '''Name''' column specifies the name which one is supposed to use in order to enforce its usage.<br />
<br />
{| class="wikitable"<br />
|-<br />
| '''Resolution''' || '''Name''' <br />
|-<br />
| 800x600 || edid/800x600.bin <br />
|-<br />
| 1024x768 || edid/1024x768.bin <br />
|-<br />
| 1280x1024 || edid/1280x1024.bin <br />
|-<br />
| 1600x1200 (kernel 3.10 or higher) || edid/1600x1200.bin<br />
|-<br />
| 1680x1050 || edid/1680x1050.bin <br />
|-<br />
| 1920x1080 || edid/1920x1080.bin <br />
|}<br />
<br />
If you are doing [[#Early_KMS_start|early KMS]], you must include the custom EDID file in the initramfs, otherwise you will run into problems.<br />
<br />
Since kernel 3.15, to load an EDID after boot, you can use debugfs instead of a kernel command line parameter. This is very useful if you swap the monitors on a connector or just for testing. Once you have an EDID file as above, run:<br />
<br />
# cat correct-edid.bin > /sys/kernel/debug/dri/0/HDMI-A-2/edid_override<br />
<br />
And to disable:<br />
<br />
# echo -n reset > /sys/kernel/debug/dri/0/HDMI-A-2/edid_override<br />
<br />
=== Forcing modes ===<br />
<br />
{{Warning|The method described below is somehow incomplete because e.g. [[Xorg]] does not take into account the resolution specified, so users are encouraged to use the method described above. However, specifying resolution with {{ic|1=video=}} command line may be useful in some scenarios.}}<br />
<br />
From [https://nouveau.freedesktop.org/wiki/KernelModeSetting the nouveau wiki]:<br />
:A mode can be forced on the kernel command line. Unfortunately, the command line option video is poorly documented in the DRM case. Bits and pieces on how to use it can be found in<br />
:* https://cgit.freedesktop.org/nouveau/linux-2.6/tree/Documentation/fb/modedb.txt<br />
:* https://cgit.freedesktop.org/nouveau/linux-2.6/tree/drivers/gpu/drm/drm_fb_helper.c <br />
<br />
The format is: <br />
<br />
video=<conn>:<xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m][eDd]<br />
<br />
* {{ic|<conn>}}: Connector, e.g. DVI-I-1, see {{ic|/sys/class/drm/}} for available connectors<br />
* {{ic|<xres> x <yres>}}: resolution<br />
* {{ic|M}}: compute a CVT mode?<br />
* {{ic|R}}: reduced blanking?<br />
* {{ic|-<bpp>}}: color depth<br />
* {{ic|@<refresh>}}: refresh rate<br />
* {{ic|i}}: interlaced (non-CVT mode)<br />
* {{ic|m}}: margins?<br />
* {{ic|e}}: output forced to on<br />
* {{ic|d}}: output forced to off<br />
* {{ic|D}}: digital output forced to on (e.g. DVI-I connector) <br />
<br />
You can override the modes of several outputs using {{ic|<nowiki>video=</nowiki>}} several times, for instance, to force {{ic|DVI}} to ''1024x768'' at ''85 Hz'' and {{ic|TV-out}} off: <br />
<br />
video=DVI-I-1:1024x768@85 video=TV-1:d<br />
<br />
To get the name and current status of connectors, you can use the following shell oneliner:<br />
<br />
{{hc|<nowiki>$ for p in /sys/class/drm/*/status; do con=${p%/status}; echo -n "${con#*/card?-}: "; cat $p; done</nowiki>|<br />
DVI-I-1: connected<br />
HDMI-A-1: disconnected<br />
VGA-1: disconnected<br />
}}<br />
<br />
== Disabling modesetting ==<br />
<br />
You may want to disable KMS for various reasons, such as getting a blank screen or a "no signal" error from the display, when using the Catalyst driver, etc. To disable KMS add {{ic|nomodeset}} as a kernel parameter. See [[Kernel parameters]] for more info.<br />
<br />
Along with {{ic|nomodeset}} kernel parameter, for Intel graphics card you need to add {{ic|1=i915.modeset=0}} and for Nvidia graphics card you need to add {{ic|1=nouveau.modeset=0}}. For Nvidia Optimus dual-graphics system, you need to add all the three kernel parameters (i.e. {{ic|1="nomodeset i915.modeset=0 nouveau.modeset=0"}}).<br />
<br />
{{Note|Some [[Xorg]] drivers will not work with KMS disabled. See the wiki page on your specific driver for details.}}</div>Ondrianhttps://wiki.archlinux.org/index.php?title=ZFS&diff=634840ZFS2020-09-10T08:26:16Z<p>Ondrian: /* ZFS is using too much RAM */ typo</p>
<hr />
<div>[[Category:File systems]]<br />
[[Category:Oracle]]<br />
[[ja:ZFS]]<br />
[[pt:ZFS]]<br />
[[zh-hans:ZFS]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related|ZFS/Virtual disks}}<br />
{{Related|Installing Arch Linux on ZFS}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:ZFS|ZFS]] is an advanced filesystem created by [[Wikipedia:Sun Microsystems|Sun Microsystems]] (now owned by Oracle) and released for OpenSolaris in November 2005. <br />
<br />
Features of ZFS include: pooled storage (integrated volume management – zpool), [[Wikipedia:Copy-on-write|Copy-on-write]], [[Wikipedia:Snapshot (computer storage)|snapshots]], data integrity verification and automatic repair (scrubbing), [[Wikipedia:RAID-Z|RAID-Z]], a maximum [[Wikipedia:Exabyte|16 Exabyte]] file size, and a maximum 256 Quadrillion [[Wikipedia:Zettabyte|Zettabytes]] storage with no limit on number of filesystems (datasets) or files[http://docs.oracle.com/cd/E19253-01/819-5461/zfsover-2/index.html]. ZFS is licensed under the [[Wikipedia:CDDL|Common Development and Distribution License]] (CDDL).<br />
<br />
Described as [https://web.archive.org/web/20060428092023/http://www.sun.com/2004-0914/feature/ "The last word in filesystems"] ZFS is stable, fast, secure, and future-proof. Being licensed under the CDDL, and thus incompatible with GPL, it is not possible for ZFS to be distributed along with the Linux Kernel. This requirement, however, does not prevent a native Linux kernel module from being developed and distributed by a third party, as is the case with [http://zfsonlinux.org/ zfsonlinux.org] (ZOL).<br />
<br />
ZOL is a project funded by the [https://www.llnl.gov/ Lawrence Livermore National Laboratory] to develop a native Linux kernel module for its massive storage requirements and super computers.<br />
<br />
{{Note|<br />
Due to potential legal incompatibilities between CDDL license of ZFS code and GPL of the Linux kernel ([https://sfconservancy.org/blog/2016/feb/25/zfs-and-linux/ ],[[wikipedia:Common_Development_and_Distribution_License#GPL_compatibility|CDDL-GPL]],[[wikipedia:ZFS#Linux|ZFS in Linux]]) - ZFS development is not supported by the kernel.<br />
<br />
As a result:<br />
<br />
* ZFSonLinux project must keep up with Linux kernel versions. After making stable ZFSonLinux release - Arch ZFS maintainers release them.<br />
* This situation sometimes locks down the normal rolling update process by unsatisfied dependencies because the new kernel version, proposed by update, is unsupported by ZFSonLinux.<br />
}}<br />
<br />
== Installation ==<br />
<br />
=== General ===<br />
<br />
{{Warning|Unless you use the [[dkms]] versions of these packages, the ZFS and SPL kernel modules are tied to a specific kernel version. It would not be possible to apply any kernel updates until updated packages are uploaded to AUR or the [[Unofficial user repositories#archzfs|archzfs]] repository.}}<br />
<br />
{{Tip| You can [[downgrade]] your linux version to the one from [[Unofficial user repositories#archzfs|archzfs]] repo if your current kernel is newer.}}<br />
<br />
Install from the [[Unofficial user repositories#archzfs|archzfs]] repository or alternatively the [[Arch User Repository]]:<br />
<br />
* {{AUR|zfs-linux}} for [http://zfsonlinux.org/ stable] releases.<br />
* {{AUR|zfs-linux-git}} for [https://github.com/zfsonlinux/zfs/releases development] releases (with support of newer kernel versions).<br />
* {{AUR|zfs-linux-lts}} for stable releases for LTS kernels.<br />
* {{AUR|zfs-linux-lts-git}} for development releases for LTS kernels.<br />
* {{AUR|zfs-linux-hardened}} for stable releases for hardened kernels.<br />
* {{AUR|zfs-linux-hardened-git}} for development releases for hardened kernels.<br />
* {{AUR|zfs-linux-zen}} for stable releases for zen kernels.<br />
* {{AUR|zfs-linux-zen-git}} for development releases for zen kernels.<br />
* {{AUR|zfs-dkms}} for versions with dynamic kernel module support.<br />
* {{AUR|zfs-dkms-git}} for development releases for versions with dynamic kernel module support.<br />
<br />
These branches have (according to them) dependency on the {{ic|zfs-utils}} package.<br />
<br />
Test the installation by issuing {{ic|zpool status}} on the command line. If an "insmod" error is produced, try {{ic|depmod -a}}.<br />
<br />
=== Root on ZFS ===<br />
<br />
See [[Install_Arch_Linux_on_ZFS#Installation|Installation]].<br />
<br />
=== DKMS ===<br />
<br />
Users can make use of DKMS [[Dynamic Kernel Module Support]] to rebuild the ZFS modules automatically with every kernel upgrade. <br />
<br />
Install {{AUR|zfs-dkms}} or {{AUR|zfs-dkms-git}} and apply the post-install instructions given by these packages.<br />
<br />
{{Tip|Add an {{ic|IgnorePkg}} entry to [[pacman.conf]] to prevent these packages from upgrading when doing a regular update.}}<br />
<br />
== Experimenting with ZFS ==<br />
<br />
Users wishing to experiment with ZFS on ''virtual block devices'' (known in ZFS terms as VDEVs) which can be simple files like {{ic|~/zfs0.img}} {{ic|~/zfs1.img}} {{ic|~/zfs2.img}} etc. with no possibility of real data loss are encouraged to see the [[Experimenting with ZFS]] article. Common tasks like building a RAIDZ array, purposefully corrupting data and recovering it, snapshotting datasets, etc. are covered.<br />
<br />
== Configuration ==<br />
<br />
ZFS is considered a "zero administration" filesystem by its creators; therefore, configuring ZFS is very straight forward. Configuration is done primarily with two commands: {{ic|zfs}} and {{ic|zpool}}.<br />
<br />
=== Automatic Start ===<br />
<br />
Currently, by default, the kernel module is not loaded at boot (see more details in https://github.com/zfsonlinux/zfs/issues/6083). To automatically load {{Ic|zfs}} module on boot, see [[Kernel module#Automatic module loading with systemd]].<br />
<br />
For ZFS to live by its "zero administration" namesake, {{Ic|zfs-import-cache.service}} must be enabled to import the pools and {{Ic|zfs-mount.service}} must be enabled to mount the filesystems available in the pools. A benefit to this is that it is not necessary to mount ZFS filesystems in {{ic|/etc/fstab}}. {{Ic|zfs-import-cache.service}} imports the zfs pools reading the file {{ic|/etc/zfs/zpool.cache}}.<br />
<br />
For each [[#Importing a pool created by id|imported pool]] you want automatically imported by {{Ic|zfs-import-cache.service}} execute:<br />
<br />
# zpool set cachefile=/etc/zfs/zpool.cache <pool><br />
<br />
{{Note|Beginning with ZOL version 0.6.5.8 the ZFS service unit files have been changed so that you need to explicitly enable any ZFS services you want to run. See [https://github.com/archzfs/archzfs/issues/72 https://github.com/archzfs/archzfs/issues/72] for more information.}}<br />
<br />
Enable the relevant service and target so the pools are automatically imported at boot time:<br />
<br />
# systemctl enable zfs-import-cache<br />
# systemctl enable zfs-import.target<br />
<br />
To mount the ZFS filesystems, you have 2 choices:<br />
* Enable the [[#Using zfs-mount.service|zfs-mount.service]]<br />
* Using [[#Using zfs-mount-generator|zfs-mount-generator]]<br />
<br />
==== Using zfs-mount.service ====<br />
<br />
In order to mount ZFS filesystems automatically on boot you need to enable the following services and targets:<br />
<br />
# systemctl enable zfs-mount<br />
# systemctl enable zfs.target<br />
<br />
==== Using zfs-mount-generator ====<br />
<br />
You can also use the zfs-mount-generator to create systemd mount units for your ZFS filesystems at boot. systemd will automatically mount the filesystems based on the mount units without having to use the {{Ic|zfs-mount.service}}. To do that, you need to:<br />
<br />
# Create the {{Ic|/etc/zfs/zfs-list.cache}} directory.<br />
# Enable the ZFS Event Daemon(ZED) script (called a ZEDLET) required to create a list of mountable ZFS filesystems. {{bc|# ln -s /usr/lib/zfs/zed.d/history_event-zfs-list-cacher.sh /etc/zfs/zed.d}}<br />
# Enable and start the ZFS Event Daemon. This service is responsible for running the script in the previous step. {{bc|# systemctl enable zfs-zed.service<br># systemctl enable zfs.target<br># systemctl start zfs-zed.service}}<br />
# You need to create an empty file named after your pool in {{Ic|/etc/zfs/zfs-list.cache}}. The ZEDLET will only update the list of filesystems if the file for the pool already exists. {{bc|# touch /etc/zfs/zfs-list.cache/<pool-name>}}<br />
# Check the contents of {{Ic|/etc/zfs/zfs-list.cache/<pool-name>}}. If it is empty, make sure that the {{Ic|zfs-zed.service}} is running and just change the canmount property of any of your ZFS filesystem by running: {{bc|1=zfs set canmount=off zroot/fs1}} This change causes ZFS to raise an event which is captured by ZED, which in turn runs the ZEDLET to update the file in {{Ic|/etc/zfs/zfs-list.cache}}. If the file in {{Ic|/etc/zfs/zfs-list.cache}} is updated, you can set the {{Ic|canmount}} property of the filesystem back by running: {{bc|1=zfs set canmount=on zroot/fs1}}<br />
You need to add a file in {{Ic|/etc/zfs/zfs-list.cache}} for each ZFS pool in your system. Make sure the pools are imported by enabling {{Ic|zfs-import-cache.service}} and {{Ic|zfs-import.target}} as [[#Automatic Start|explained above]].<br />
<br />
== Storage pools ==<br />
<br />
It is not necessary to partition the drives before creating the ZFS filesystem. It is recommended to point ZFS at an entire disk (ie. `/dev/sdx` rather than `/dev/sdx1`), which will [https://www.reddit.com/r/zfs/comments/667na0/zfs_on_raw_or_gpt/dgh0l9t/ automatically create a GPT partition table] and add an 8 MB reserved partition at the end of the disk for legacy bootloaders. However, you can specify a partition or a file within an existing filesystem, if you wish to create multiple volumes with different redundancy properties.<br />
<br />
{{Note|If some or all device have been used in a software RAID set it is paramount to [[mdadm#Prepare the devices|erase any old RAID configuration information]].}}<br />
<br />
{{Warning|For [[Advanced Format]] Disks with 4KB sector size, an ashift of 12 is recommended for best performance. Advanced Format disks emulate a sector size of 512 bytes for compatibility with legacy systems, this causes ZFS to sometimes use an ashift option number that is not ideal. Once the pool has been created, the only way to change the ashift option is to recreate the pool. Using an ashift of 12 would also decrease available capacity. See [https://github.com/zfsonlinux/zfs/wiki/faq#performance-considerations 1.10 What’s going on with performance?], [https://github.com/zfsonlinux/zfs/wiki/faq#advanced-format-disks 1.15 How does ZFS on Linux handle Advanced Format disks?], and [http://wiki.illumos.org/display/illumos/ZFS+and+Advanced+Format+disks ZFS and Advanced Format disks].}}<br />
<br />
=== Identify disks ===<br />
<br />
[https://github.com/zfsonlinux/zfs/wiki/faq#selecting-dev-names-when-creating-a-pool ZFS on Linux] recommends using device IDs when creating ZFS storage pools of less than 10 devices. Use [[Persistent block device naming#by-id and by-path]] to identify the list of drives to be used for ZFS pool. <br />
<br />
The disk IDs should look similar to the following:<br />
<br />
{{hc|$ ls -lh /dev/disk/by-id/|<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JKRR -> ../../sdc<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JTM1 -> ../../sde<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KBP8 -> ../../sdd<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KDGY -> ../../sdb}}<br />
<br />
{{Warning|If you create zpools using device names (e.g. {{ic|/dev/sda}},{{ic|/dev/sdb}},...) ZFS might not be able to detect zpools intermittently on boot.}}<br />
<br />
==== Using GPT labels ====<br />
<br />
{{Style|Missing references to [[Persistent block device naming]], it is useless to explain the differences (or even what they are) here.}}<br />
<br />
Disk labels and UUID can also be used for ZFS mounts by using [[GUID Partition Table|GPT]] partitions. ZFS drives have labels but Linux is unable to read them at boot. Unlike [[Master Boot Record|MBR]] partitions, GPT partitions directly support both UUID and labels independent of the format inside the partition. Partitioning rather than using the whole disk for ZFS offers two additional advantages. The OS does not generate bogus partition numbers from whatever unpredictable data ZFS has written to the partition sector, and if desired, you can easily over provision SSD drives, and slightly over provision spindle drives to ensure that different models with slightly different sector counts can zpool replace into your mirrors. This is a lot of organization and control over ZFS using readily available tools and techniques at almost zero cost.<br />
<br />
Use [[GUID Partition Table|gdisk]] to partition the all or part of the drive as a single partition. gdisk does not automatically name partitions so if partition labels are desired use gdisk command "c" to label the partitions. Some reasons you might prefer labels over UUID are: labels are easy to control, labels can be titled to make the purpose of each disk in your arrangement readily apparent, and labels are shorter and easier to type. These are all advantages when the server is down and the heat is on. GPT partition labels have plenty of space and can store most international characters [[wikipedia:GUID_Partition_Table#Partition_entries]] allowing large data pools to be labeled in an organized fashion.<br />
<br />
Drives partitioned with GPT have labels and UUID that look like this. <br />
<br />
{{hc|$ ls -l /dev/disk/by-partlabel|<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 zfsdata1 -> ../../sdd1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 zfsdata2 -> ../../sdc1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:59 zfsl2arc -> ../../sda1}}<br />
<br />
{{hc|$ ls -l /dev/disk/by-partuuid|<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 148c462c-7819-431a-9aba-5bf42bb5a34e -> ../../sdd1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:59 4f95da30-b2fb-412b-9090-fc349993df56 -> ../../sda1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 e5ccef58-5adf-4094-81a7-3bac846a885f -> ../../sdc1}}<br />
<br />
{{Tip|To minimize typing and copy/paste errors, set a local variable with the target PARTUUID: {{ic|<nowiki>$ UUID=$(lsblk --noheadings --output PARTUUID /dev/sd</nowiki>''XY''<nowiki>)</nowiki>}} }}<br />
<br />
=== Creating ZFS pools ===<br />
<br />
To create a ZFS pool:<br />
<br />
# zpool create -f -m <mount> <pool> [raidz(2|3)|mirror] <ids><br />
<br />
{{Tip|One may want to read [[#Advanced Format disks]] first as it may be recommend to set {{ic|ashift}} on pool creation.}}<br />
<br />
* '''create''': subcommand to create the pool.<br />
<br />
* '''-f''': Force creating the pool. This is to overcome the "EFI label error". See [[#Does not contain an EFI label]].<br />
<br />
* '''-m''': The mount point of the pool. If this is not specified, then the pool will be mounted to {{ic|/<pool>}}.<br />
<br />
* '''pool''': This is the name of the pool.<br />
<br />
* '''raidz(2|3)|mirror''': This is the type of virtual device that will be created from the pool of devices, raidz is a single disk of parity, raidz2 for 2 disks of parity and raidz3 for 3 disks of parity, similar to raid5 and raid6. Also available is '''mirror''', which is similar to raid1 or raid10, but is not constrained to just 2 device. If not specified, each device will be added as a vdev which is similar to raid0. After creation, a device can be added to each single drive vdev to turn it into a mirror, which can be useful for migrating data.<br />
<br />
* '''ids''': The [[Persistent_block_device_naming#by-id_and_by-path|ID's]] of the drives or partitions that to include into the pool.<br />
<br />
Create pool with single raidz vdev:<br />
<br />
# zpool create -f -m /mnt/data bigdata \<br />
raidz \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
Create pool with two mirror vdevs:<br />
<br />
# zpool create -f -m /mnt/data bigdata \<br />
mirror \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
mirror \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
==== Advanced Format disks ====<br />
<br />
At pool creation, '''ashift=12''' should always be used, except with SSDs that have 8k sectors where '''ashift=13''' is correct. A vdev of 512 byte disks using 4k sectors will not experience performance issues, but a 4k disk using 512 byte sectors will. Since '''ashift''' cannot be changed after pool creation, even a pool with only 512 byte disks should use 4k because those disks may need to be replaced with 4k disks or the pool may be expanded by adding a vdev composed of 4k disks. Because correct detection of 4k disks is not reliable, {{ic|<nowiki>-o ashift=12</nowiki>}} should always be specified during pool creation. See the [https://github.com/zfsonlinux/zfs/wiki/faq#advanced-format-disks ZFS on Linux FAQ] for more details.<br />
<br />
{{Tip|Use {{man|8|blockdev}} (part of {{Pkg|util-linux}}) to print the sector size reported by the device's ioctls: {{ic|blockdev --getpbsz /dev/sd''XY''}} as the root user.}}<br />
<br />
Create pool with ashift=12 and single raidz vdev:<br />
<br />
# zpool create -f -o ashift=12 -m /mnt/data bigdata \<br />
raidz \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
==== GRUB-compatible pool creation ====<br />
<br />
{{note|This section frequently goes out of date with updates to GRUB and ZFS. Consult the manual pages for the most up-to-date information.}}<br />
<br />
By default, ''zpool create'' enables all features on a pool. If {{ic|/boot}} resides on ZFS when using [[GRUB]] you must only enable features supported by GRUB otherwise GRUB will not be able to read the pool. GRUB 2.02 supports the read-write features {{ic|lz4_compress}}, {{ic|hole_birth}}, {{ic|embedded_data}}, {{ic|extensible_dataset}}, and {{ic|large_blocks}}; this is not suitable for all the features of ZFSonLinux 0.8.0, and must have unsupported features disabled. We can explicitly name features to enable with the {{ic|-d}} argument to {{ic|zpool create}}, which disables all features by default.<br />
<br />
You can create a pool with only the compatible features enabled:<br />
<br />
# zpool create -d -o feature@allocation_classes=enabled \<br />
-o feature@async_destroy=enabled \<br />
-o feature@bookmarks=enabled \<br />
-o feature@embedded_data=enabled \<br />
-o feature@empty_bpobj=enabled \<br />
-o feature@enabled_txg=enabled \<br />
-o feature@extensible_dataset=enabled \<br />
-o feature@filesystem_limits=enabled \<br />
-o feature@hole_birth=enabled \<br />
-o feature@large_blocks=enabled \<br />
-o feature@lz4_compress=enabled \<br />
-o feature@project_quota=enabled \<br />
-o feature@resilver_defer=enabled \<br />
-o feature@spacemap_histogram=enabled \<br />
-o feature@spacemap_v2=enabled \<br />
-o feature@userobj_accounting=enabled \<br />
-o feature@zpool_checkpoint=enabled \<br />
$POOL_NAME $VDEVS<br />
<br />
=== Verifying pool status ===<br />
<br />
If the command is successful, there will be no output. Using the [[mount]] command will show that the pool is mounted. Using {{ic|zpool status}} will show that the pool has been created:<br />
<br />
{{hc|# zpool status -v|<br />
pool: bigdata<br />
state: ONLINE<br />
scan: none requested<br />
config:<br />
<br />
NAME STATE READ WRITE CKSUM<br />
bigdata ONLINE 0 0 0<br />
-0 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KDGY-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JKRR-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KBP8-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JTM1-part1 ONLINE 0 0 0<br />
<br />
errors: No known data errors<br />
}}<br />
<br />
At this point it would be good to reboot the machine to ensure that the ZFS pool is mounted at boot. It is best to deal with all errors before transferring data.<br />
<br />
=== Importing a pool created by id ===<br />
<br />
Eventually a pool may fail to auto mount and you need to import to bring your pool back. Take care to avoid the most obvious solution.<br />
<br />
{{Warning|Do not run {{ic|zpool import ''pool''}}! This will import your pools using {{ic|/dev/sd?}} which will lead to problems the next time you rearrange your drives. This may be as simple as rebooting with a USB drive left in the machine, which harkens back to a time when PCs would not boot when a floppy disk was left in a machine.}}<br />
<br />
Adapt one of the following commands to import your pool so that pool imports retain the persistence they were created with:<br />
<br />
# zpool import -d /dev/disk/by-id bigdata<br />
# zpool import -d /dev/disk/by-partlabel bigdata<br />
# zpool import -d /dev/disk/by-partuuid bigdata<br />
<br />
{{Note|Use the {{ic|-l}} flag when importing a pool that contains [[#Native encryption|encrypted datasets keys]]:<br />
# zpool import -l -d /dev/disk/by-id bigdata<br />
}}<br />
<br />
Finally check the state of the pool:<br />
<br />
# zpool status -v bigdata<br />
<br />
=== Destroy a storage pool ===<br />
<br />
ZFS makes it easy to destroy a mounted storage pool, removing all metadata about the ZFS device.<br />
<br />
{{Warning|This command destroys '''any data''' containing in the pool and/or dataset.}}<br />
<br />
To destroy the pool:<br />
# zpool destroy <pool><br />
<br />
To destroy a dataset:<br />
# zfs destroy <pool>/<dataset><br />
<br />
And now when checking the status:<br />
<br />
{{hc|# zpool status|<br />
no pools available<br />
}}<br />
<br />
=== Exporting a storage pool ===<br />
<br />
If a storage pool is to be used on another system, it will first need to be exported. It is also necessary to export a pool if it has been imported from the archiso as the hostid is different in the archiso as it is in the booted system. The zpool command will refuse to import any storage pools that have not been exported. It is possible to force the import with the {{ic|-f}} argument, but this is considered bad form.<br />
<br />
Any attempts made to import an un-exported storage pool will result in an error stating the storage pool is in use by another system. This error can be produced at boot time abruptly abandoning the system in the busybox console and requiring an archiso to do an emergency repair by either exporting the pool, or adding the {{ic|zfs_force&#61;1}} to the kernel boot parameters (which is not ideal). See [[#On boot the zfs pool does not mount stating: "pool may be in use from other system"]]<br />
<br />
To export a pool:<br />
<br />
# zpool export <pool><br />
<br />
=== Extending an existing zpool ===<br />
<br />
A device (a partition or a disk) can be added to an existing zpool:<br />
<br />
# zpool add <pool> <device-id><br />
<br />
To import a pool which consists of multiple devices:<br />
<br />
# zpool import -d <device-id-1> -d <device-id-2> <pool><br />
<br />
or simply:<br />
<br />
# zpool import -d /dev/disk-by-id/ <pool><br />
<br />
=== Renaming a zpool ===<br />
<br />
Renaming a zpool that is already created is accomplished in 2 steps:<br />
<br />
# zpool export oldname<br />
# zpool import oldname newname<br />
<br />
=== Setting a different mount point ===<br />
<br />
The mount point for a given zpool can be moved at will with one command:<br />
# zfs set mountpoint=/foo/bar poolname<br />
<br />
== Creating datasets ==<br />
<br />
Users can optionally create a dataset under the zpool as opposed to manually creating directories under the zpool. Datasets allow for an increased level of control (quotas for example) in addition to snapshots. To be able to create and mount a dataset, a directory of the same name must not pre-exist in the zpool. To create a dataset, use:<br />
<br />
# zfs create <nameofzpool>/<nameofdataset><br />
<br />
It is then possible to apply ZFS specific attributes to the dataset. For example, one could assign a quota limit to a specific directory within a dataset:<br />
<br />
# zfs set quota=20G <nameofzpool>/<nameofdataset>/<directory><br />
<br />
To see all the commands available in ZFS, see {{man|8|zfs|url=}} or {{man|8|zpool|url=}}.<br />
<br />
=== Native encryption ===<br />
<br />
ZFS offers the following supported encryption options: {{ic|aes-128-ccm}}, {{ic|aes-192-ccm}}, {{ic|aes-256-ccm}}, {{ic|aes-128-gcm}}, {{ic|aes-192-gcm}} and {{ic|aes-256-gcm}}. When encryption is set to {{ic|on}}, {{ic|aes-256-gcm}} will be used.<br />
<br />
The following keyformats are supported: {{ic|passphrase}}, {{ic|raw}}, {{ic|hex}}.<br />
<br />
One can also specify/increase the default iterations of PBKDF2 when using {{ic|passphrase}} with {{ic|-o pbkdf2iters <n>}}, although it may increase the decryption time.<br />
<br />
{{Note|<br />
* Native ZFS encryption has been made available in the stable 0.8.0 release or newer. Previously it was only available in development versions provided by packages like {{AUR|zfs-linux-git}}, {{AUR|zfs-dkms-git}} or other development builds. Users who were only using the development versions for the native encryption, may now switch to the stable releases if they wish.<br />
* The default encryption suite was changed from {{ic|aes-256-ccm}} to {{ic|aes-256-gcm}} in the 0.8.4 release.<br />
* To import a pool with keys, one needs to specify the {{ic|-l}} flag, without this flag encrypted datasets will be left unavailable until the keys are loaded. See [[#Importing a pool created by id]].}}<br />
<br />
To create a dataset including native encryption with a passphrase, use:<br />
<br />
# zfs create -o encryption=on -o keyformat=passphrase <nameofzpool>/<nameofdataset><br />
<br />
To use a key instead of using a passphrase:<br />
<br />
# dd if=/dev/random of=/path/to/key bs=1 count=32<br />
# zfs create -o encryption=on -o keyformat=raw -o keylocation=file:///path/to/key <nameofzpool>/<nameofdataset><br />
<br />
To verify the key location:<br />
# zfs get keylocation <nameofzpool>/<nameofdataset><br />
<br />
To change the key location:<br />
<br />
# zfs set keylocation=file:///path/to/key <nameofzpool>/<nameofdataset><br />
<br />
You can also manually load the keys by using one of the following commands:<br />
<br />
# zfs load-key <nameofzpool>/<nameofdataset> # load key for a specific dataset<br />
# zfs load-key -a # load all keys<br />
# zfs load-key -r zpool/dataset # load all keys in a dataset<br />
<br />
To mount the created encrypted dataset:<br />
<br />
# zfs mount <nameofzpool>/<nameofdataset><br />
<br />
==== Unlock at boot time ====<br />
It is possible to automatically unlock a pool dataset on boot time by using a [[systemd]] unit. For example create the following service to unlock any specific dataset: <br />
<br />
{{hc|/etc/systemd/system/zfs-load-key@.service|2=<br />
[Unit]<br />
Description=Load %I encryption keys<br />
Before=systemd-user-sessions.service<br />
After=zfs-import.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/bash -c 'until (systemd-ask-password "Encrypted ZFS password for %I" --no-tty <nowiki>|</nowiki> zfs load-key %I); do echo "Try again!"; done'<br />
<br />
[Install]<br />
WantedBy=zfs-mount.service<br />
}}<br />
<br />
[[Enable]]/[[start]] the service for each encrypted dataset, e.g. {{ic|systemctl enable zfs-load-key@pool0-dataset0}} as the root user. Note the use of {{ic|-}}, which is an escaped {{ic|/}} in systemd unit definitions. See {{ic|systemd-escape(1)}} for more info.<br />
{{Note|The {{ic|1=Before=systemd-user-sessions.service}} ensures that systemd-ask-password is invoked before the local IO devices are handed over to the [[desktop environment]].}}<br />
<br />
An alternative is to load all possible keys:<br />
<br />
{{hc|/etc/systemd/system/zfs-load-key.service|2=<br />
[Unit]<br />
Description=Load encryption keys<br />
DefaultDependencies=no<br />
After=zfs-import.target<br />
Before=zfs-mount.service<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/bash -c '/usr/bin/zfs load-key -a'<br />
<br />
[Install]<br />
WantedBy=zfs-mount.service<br />
}}<br />
<br />
[[Enable]]/[[start]] {{ic|zfs-load-key.service}}.<br />
<br />
=== Swap volume ===<br />
<br />
{{Warning|On systems with extremely high memory pressure, using a zvol for swap can result in lockup, regardless of how much swap is still available. This issue is currently being investigated in https://github.com/zfsonlinux/zfs/issues/7734}}<br />
<br />
ZFS does not allow to use swapfiles, but users can use a ZFS volume (ZVOL) as swap. It is important to set the ZVOL block size to match the system page size, which can be obtained by the {{ic|getconf PAGESIZE}} command (default on x86_64 is 4KiB). Another option useful for keeping the system running well in low-memory situations is not caching the ZVOL data.<br />
<br />
Create a 8 GiB zfs volume:<br />
<br />
# zfs create -V 8G -b $(getconf PAGESIZE) -o compression=zle \<br />
-o logbias=throughput -o sync=always\<br />
-o primarycache=metadata -o secondarycache=none \<br />
-o com.sun:auto-snapshot=false <pool>/swap<br />
<br />
Prepare it as swap partition:<br />
<br />
# mkswap -f /dev/zvol/<pool>/swap<br />
# swapon /dev/zvol/<pool>/swap<br />
<br />
To make it permanent, edit {{ic|/etc/fstab}}. ZVOLs support discard, which can potentially help ZFS's block allocator and reduce fragmentation for all other datasets when/if swap is not full.<br />
<br />
Add a line to {{ic|/etc/fstab}}:<br />
<br />
/dev/zvol/<pool>/swap none swap discard 0 0<br />
<br />
=== Access Control Lists ===<br />
<br />
To use [[ACL]] on a dataset:<br />
<br />
# zfs set acltype=posixacl <nameofzpool>/<nameofdataset><br />
# zfs set xattr=sa <nameofzpool>/<nameofdataset><br />
<br />
Setting {{ic|xattr}} is recommended for performance reasons [https://github.com/zfsonlinux/zfs/issues/170#issuecomment-27348094].<br />
<br />
It may be preferable to enable ACL on the zpool as datasets will inherit the ACL parameters. Setting {{ic|1=aclinherit=passthrough}} may be wanted as the default mode is {{ic|restricted}} [https://docs.oracle.com/cd/E19120-01/open.solaris/817-2271/gbaaz/index.html]:<br />
<br />
# zfs set aclinherit=passthrough <nameofzpool><br />
# zfs set acltype=posixacl <nameofzpool><br />
# zfs set xattr=sa <nameofzpool><br />
<br />
=== Databases ===<br />
<br />
ZFS, unlike most other file systems, has a variable record size, or what is commonly referred to as a block size. By default, the recordsize on ZFS is 128KiB, which means it will dynamically allocate blocks of any size from 512B to 128KiB depending on the size of file being written. This can often help fragmentation and file access, at the cost that ZFS would have to allocate new 128KiB blocks each time only a few bytes are written to.<br />
<br />
Most RDBMSes work in 8KiB-sized blocks by default. Although the block size is tunable for [[MySQL|MySQL/MariaDB]], [[PostgreSQL]], and [[Oracle Database]], all three of them use an 8KiB block size ''by default''. For both performance concerns and keeping snapshot differences to a minimum (for backup purposes, this is helpful), it is usually desirable to tune ZFS instead to accommodate the databases, using a command such as:<br />
<br />
# zfs set recordsize=8K <pool>/postgres<br />
<br />
These RDBMSes also tend to implement their own caching algorithm, often similar to ZFS's own ARC. In the interest of saving memory, it is best to simply disable ZFS's caching of the database's file data and let the database do its own job:<br />
<br />
# zfs set primarycache=metadata <pool>/postgres<br />
<br />
If your pool has no configured log devices, ZFS reserves space on the pool's data disks for its intent log (the ZIL). ZFS uses this for crash recovery, but databases are often syncing their data files to the file system on their own transaction commits anyway. The end result of this is that ZFS will be committing data '''twice''' to the data disks, and it can severely impact performance. You can tell ZFS to prefer to not use the ZIL, and in which case, data is only committed to the file system once. Setting this for non-database file systems, or for pools with configured log devices, can actually ''negatively'' impact the performance, so beware:<br />
<br />
# zfs set logbias=throughput <pool>/postgres<br />
<br />
These can also be done at file system creation time, for example:<br />
<br />
# zfs create -o recordsize=8K \<br />
-o primarycache=metadata \<br />
-o mountpoint=/var/lib/postgres \<br />
-o logbias=throughput \<br />
<pool>/postgres<br />
<br />
Please note: these kinds of tuning parameters are ideal for specialized applications like RDBMSes. You can easily ''hurt'' ZFS's performance by setting these on a general-purpose file system such as your /home directory.<br />
<br />
=== /tmp ===<br />
<br />
If you would like to use ZFS to store your /tmp directory, which may be useful for storing arbitrarily-large sets of files or simply keeping your RAM free of idle data, you can generally improve performance of certain applications writing to /tmp by disabling file system sync. This causes ZFS to ignore an application's sync requests (eg, with {{ic|fsync}} or {{ic|O_SYNC}}) and return immediately. While this has severe application-side data consistency consequences (never disable sync for a database!), files in /tmp are less likely to be important and affected. Please note this does ''not'' affect the integrity of ZFS itself, only the possibility that data an application expects on-disk may not have actually been written out following a crash.<br />
<br />
# zfs set sync=disabled <pool>/tmp<br />
<br />
Additionally, for security purposes, you may want to disable '''setuid''' and '''devices''' on the /tmp file system, which prevents some kinds of privilege-escalation attacks or the use of device nodes:<br />
<br />
# zfs set setuid=off <pool>/tmp<br />
# zfs set devices=off <pool>/tmp<br />
<br />
Combining all of these for a create command would be as follows:<br />
<br />
# zfs create -o setuid=off -o devices=off -o sync=disabled -o mountpoint=/tmp <pool>/tmp<br />
<br />
Please note, also, that if you want /tmp on ZFS, you will need to mask (disable) [[systemd]]'s automatic tmpfs-backed /tmp, else ZFS will be unable to mount your dataset at boot-time or import-time:<br />
<br />
# systemctl mask tmp.mount<br />
<br />
== Tuning ==<br />
<br />
=== General ===<br />
<br />
ZFS pools and datasets can be further adjusted using parameters.<br />
<br />
{{Note|All settable properties, with the exception of quotas and reservations, inherit their value from the parent dataset.}}<br />
<br />
To retrieve the current pool parameter status:<br />
<br />
# zfs get all <pool><br />
<br />
To retrieve the current dataset parameter status:<br />
<br />
# zfs get all <pool>/<dataset><br />
<br />
To disable access time (atime), which is enabled by default:<br />
<br />
# zfs set atime=off <pool><br />
<br />
To disable access time (atime) on a particular dataset:<br />
<br />
# zfs set atime=off <pool>/<dataset><br />
<br />
An alternative to turning off atime completely, {{ic|relatime}} is available. This brings the default ext4/XFS atime semantics to ZFS, where access time is only updated if the modified time or changed time changes, or if the existing access time has not been updated within the past 24 hours. It is a compromise between {{ic|1=atime=off}} and {{ic|1=atime=on}}. This property ''only'' takes effect if {{ic|atime}} is {{ic|on}}:<br />
<br />
# zfs set atime=on <pool><br />
# zfs set relatime=on <pool><br />
<br />
Compression is just that, transparent compression of data. ZFS supports a few different algorithms, presently lz4 is the default, ''gzip'' is also available for seldom-written yet highly-compressible data; consult the [http://open-zfs.org/wiki/Performance_tuning#Compression OpenZFS Wiki] for more details. <br />
<br />
To enable compression:<br />
<br />
# zfs set compression=on <pool><br />
<br />
To reset a property of a pool and/or dataset to it's default state, use {{ic|zfs inherit}}:<br />
<br />
# zfs inherit -rS atime <pool><br />
# zfs inherit -rS atime <pool>/<dataset><br />
<br />
{{Warning|Using the {{ic|-r}} flag will recursively reset all datasets of the zpool.}}<br />
<br />
=== Scrubbing ===<br />
<br />
Whenever data is read and ZFS encounters an error, it is silently repaired when possible, rewritten back to disk and logged so you can obtain an overview of errors on your pools. There is no fsck or equivalent tool for ZFS. Instead, ZFS supports a feature known as scrubbing. This traverses through all the data in a pool and verifies that all blocks can be read.<br />
<br />
To scrub a pool:<br />
<br />
# zpool scrub <pool><br />
<br />
To cancel a running scrub:<br />
<br />
# zpool scrub -s <pool><br />
<br />
==== How often should I do this? ====<br />
<br />
From the Oracle blog post [https://blogs.oracle.com/wonders-of-zfs-storage/disk-scrub-why-and-when-v2 Disk Scrub - Why and When?]:<br />
<br />
:This question is challenging for Support to answer, because as always the true answer is "It Depends". So before I offer a general guideline, here are a few tips to help you create an answer more tailored to your use pattern.<br />
<br />
:* What is the expiration of your oldest backup? You should probably scrub your data at least as often as your oldest tapes expire so that you have a known-good restore point.<br />
:* How often are you experiencing disk failures? While the recruitment of a hot-spare disk invokes a "resilver" -- a targeted scrub of just the VDEV which lost a disk -- you should probably scrub at least as often as you experience disk failures on average in your specific environment.<br />
:* How often is the oldest piece of data on your disk read? You should scrub occasionally to prevent very old, very stale data from experiencing bit-rot and dying without you knowing it.<br />
<br />
:If any of your answers to the above are "I do not know", the general guideline is: you should probably be scrubbing your zpool at least once per month. It is a schedule that works well for most use cases, provides enough time for scrubs to complete before starting up again on all but the busiest & most heavily-loaded systems, and even on very large zpools (192+ disks) should complete fairly often between disk failures.<br />
<br />
In the [https://pthree.org/2012/12/11/zfs-administration-part-vi-scrub-and-resilver/ ZFS Administration Guide] by Aaron Toponce, he advises to scrub consumer disks once a week.<br />
<br />
==== Start with a service or timer ====<br />
Using a [[systemd]] timer/service it is possible to automatically scrub pools.<br />
<br />
To perform scrubbing monthly on a particular pool:<br />
<br />
{{hc|/etc/systemd/system/zfs-scrub@.timer|2=<br />
[Unit]<br />
Description=Monthly zpool scrub on %i<br />
<br />
[Timer]<br />
OnCalendar=monthly<br />
AccuracySec=1h<br />
Persistent=true<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/zfs-scrub@.service|2=<br />
[Unit]<br />
Description=zpool scrub on %i<br />
<br />
[Service]<br />
Nice=19<br />
IOSchedulingClass=idle<br />
KillSignal=SIGINT<br />
ExecStart=/usr/bin/zpool scrub %i<br />
}}<br />
<br />
[[Enable]]/[[start]] {{ic|zfs-scrub@''pool-to-scrub''.timer}} unit for monthly scrubbing the specified zpool.<br />
<br />
=== SSD Caching ===<br />
<br />
You can add SSD devices as a write intent log (external ZIL or SLOG) and also as a layer 2 adaptive replacement cache (L2ARC). The process to add them is very similar to adding a new VDEV.<br />
<br />
All of the below references to device-id are the IDs from {{ic|/dev/disk/by-id/*}}.<br />
<br />
==== SLOG ====<br />
<br />
To add a mirrored SLOG:<br />
<br />
# zpool add <pool> log mirror <device-id-1> <device-id-2><br />
<br />
Or to add a single device SLOG (unsafe):<br />
<br />
# zpool add <pool> log <device-id><br />
<br />
Because the SLOG device stores data that has not been written to the pool, it is important to use devices that can finish writes when power is lost. It is also important to use redundancy, since a device failure can cause data loss. In addition, the SLOG is only used for sync writes, so may not provide any performance improvement.<br />
<br />
==== L2ARC ====<br />
<br />
To add L2ARC:<br />
<br />
# zpool add <pool> cache <device-id><br />
<br />
Because every block cached in L2ARC uses a small amount of memory, it is generally only useful in workloads where the amount of hot data is *bigger* than the maximum amount of memory that can fit in the computer, but small enough to fit into L2ARC. It is also cleared at reboot and is only a read cache, so redundancy is unnecessary. Un-intuitively, L2ARC can actually harm performance since it takes memory away from ARC.<br />
<br />
=== ZVOLs ===<br />
<br />
ZFS volumes (ZVOLs) can suffer from the same block size-related issues as RDBMSes, but it is worth noting that the default recordsize for ZVOLs is 8 KiB already. If possible, it is best to align any partitions contained in a ZVOL to your recordsize (current versions of fdisk and gdisk by default automatically align at 1MiB segments, which works), and file system block sizes to the same size. Other than this, you might tweak the '''recordsize''' to accommodate the data inside the ZVOL as necessary (though 8 KiB tends to be a good value for most file systems, even when using 4 KiB blocks on that level).<br />
<br />
==== RAIDZ and Advanced Format physical disks ====<br />
<br />
Each block of a ZVOL gets its own parity disks, and if you have physical media with logical block sizes of 4096B, 8192B, or so on, the parity needs to be stored in whole physical blocks, and this can drastically increase the space requirements of a ZVOL, requiring 2× or more physical storage capacity than the ZVOL's logical capacity. Setting the '''recordsize''' to 16k or 32k can help reduce this footprint drastically.<br />
<br />
See [https://github.com/zfsonlinux/zfs/issues/1807 ZFS on Linux issue #1807 for details]<br />
<br />
=== I/O Scheduler ===<br />
<br />
When the pool is imported, for whole disk vdevs, the block device I/O scheduler is set to {{ic|zfs_vdev_scheduler}} [https://github.com/zfsonlinux/zfs/wiki/ZFS-on-Linux-Module-Parameters#zfs_vdev_scheduler]. The most common schedulers are: ''noop'', ''cfq'', ''bfq'', and ''deadline''.<br />
<br />
In some cases, the scheduler is not changeable using this method. Known schedulers that cannot be changed are: ''scsi_mq'' and ''none''. In these cases, the scheduler is unchanged and an error message can be reported to logs. [[Improving_performance#Changing_I/O_scheduler|Manually setting]] one of the common schedulers used by {{ic|zfs_vdev_scheduler}} can result in more consistent performance.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Creating a zpool fails ===<br />
<br />
If the following error occurs then it can be fixed.<br />
<br />
# the kernel failed to rescan the partition table: 16<br />
# cannot label 'sdc': try using parted(8) and then provide a specific slice: -1<br />
<br />
One reason this can occur is because [https://github.com/zfsonlinux/zfs/issues/2582 ZFS expects pool creation to take less than 1 second]. This is a reasonable assumption under ordinary conditions, but in many situations it may take longer. Each drive will need to be cleared again before another attempt can be made.<br />
<br />
# parted /dev/sda rm 1<br />
# parted /dev/sda rm 1<br />
# dd if=/dev/zero of=/dev/sdb bs=512 count=1<br />
# zpool labelclear /dev/sda<br />
<br />
A brute force creation can be attempted over and over again, and with some luck the ZPool creation will take less than 1 second.<br />
Once cause for creation slowdown can be slow burst read writes on a drive. By reading from the disk in parallell to ZPool creation, it may be possible to increase burst speeds.<br />
<br />
# dd if=/dev/sda of=/dev/null<br />
<br />
This can be done with multiple drives by saving the above command for each drive to a file on separate lines and running <br />
<br />
# cat $FILE | parallel<br />
<br />
Then run ZPool creation at the same time.<br />
<br />
=== ZFS is using too much RAM ===<br />
<br />
By default, ZFS caches file operations ([[wikipedia:Adaptive replacement cache|ARC]]) using up to two-thirds of available system memory on the host. To adjust the ARC size, add the following to the [[Kernel parameters]] list:<br />
<br />
zfs.zfs_arc_max=536870912 # (for 512MB)<br />
<br />
In case that the default value of {{ic|zfs_arc_min}} (1/32 of system memory) is higher than the specified {{ic|zfs_arc_max}} it is needed to add also the following to the [[Kernel parameters]] list:<br />
<br />
zfs.zfs_arc_min=268435456 # (for 256MB, needs to be lower than zfs.zfs_arc_max)<br />
<br />
For a more detailed description, as well as other configuration options, see [http://wiki.gentoo.org/wiki/ZFS#ARC gentoo-wiki:zfs#arc].<br />
<br />
=== Does not contain an EFI label ===<br />
<br />
The following error will occur when attempting to create a zfs filesystem,<br />
<br />
/dev/disk/by-id/<id> does not contain an EFI label but it may contain partition<br />
<br />
The way to overcome this is to use {{ic|-f}} with the zfs create command.<br />
<br />
=== No hostid found ===<br />
<br />
An error that occurs at boot with the following lines appearing before initscript output:<br />
<br />
ZFS: No hostid found on kernel command line or /etc/hostid.<br />
<br />
This warning occurs because the ZFS module does not have access to the spl hosted. There are two solutions, for this. Either place the spl hostid in the [[kernel parameters]] in the boot loader. For example, adding {{ic|1=spl.spl_hostid=0x00bab10c}}.<br />
<br />
The other solution is to make sure that there is a hostid in {{ic|/etc/hostid}}, and then [[regenerate the initramfs]] image. Which will copy the hostid into the initramfs image.<br />
<br />
=== Pool cannot be found while booting from SAS/SCSI devices ===<br />
<br />
In case you are booting a SAS/SCSI based, you might occassionally get boot problems where the pool you are trying to boot from cannot be found. A likely reason for this is that your devices are initialized too late into the process. That means that zfs cannot find any devices at the time when it tries to assemble your pool.<br />
<br />
In this case you should force the scsi driver to wait for devices to come online before continuing. You can do this by putting this into {{ic|/etc/modprobe.d/zfs.conf}}:<br />
<br />
{{hc|1=/etc/modprobe.d/zfs.conf|2=<br />
options scsi_mod scan=sync<br />
}}<br />
<br />
Afterwards, [[regenerate the initramfs]].<br />
<br />
This works because the zfs hook will copy the file at {{ic|/etc/modprobe.d/zfs.conf}} into the initcpio which will then be used at build time.<br />
<br />
=== On boot the zfs pool does not mount stating: "pool may be in use from other system" ===<br />
<br />
==== Unexported pool ====<br />
<br />
If the new installation does not boot because the zpool cannot be imported, chroot into the installation and properly export the zpool. See [[#Emergency chroot repair with archzfs]].<br />
<br />
Once inside the chroot environment, load the ZFS module and force import the zpool,<br />
<br />
# zpool import -a -f<br />
<br />
now export the pool:<br />
<br />
# zpool export <pool><br />
<br />
To see the available pools, use,<br />
<br />
# zpool status<br />
<br />
It is necessary to export a pool because of the way ZFS uses the hostid to track the system the zpool was created on. The hostid is generated partly based on the network setup. During the installation in the archiso the network configuration could be different generating a different hostid than the one contained in the new installation. Once the zfs filesystem is exported and then re-imported in the new installation, the hostid is reset. See [http://osdir.com/ml/zfs-discuss/2011-06/msg00227.html Re: Howto zpool import/export automatically? - msg#00227]{{Dead link|2020|04|03|status=404}}.<br />
<br />
If ZFS complains about "pool may be in use" after every reboot, properly export pool as described above, and then [[regenerate the initramfs]] in normally booted system.<br />
<br />
==== Incorrect hostid ====<br />
<br />
Double check that the pool is properly exported. Exporting the zpool clears the hostid marking the ownership. So during the first boot the zpool should mount correctly. If it does not there is some other problem.<br />
<br />
Reboot again, if the zfs pool refuses to mount it means the hostid is not yet correctly set in the early boot phase and it confuses zfs. Manually tell zfs the correct number, once the hostid is coherent across the reboots the zpool will mount correctly.<br />
<br />
Boot using zfs_force and write down the hostid. This one is just an example.<br />
<br />
{{hc|$ hostid|<br />
0a0af0f8<br />
}}<br />
<br />
This number have to be added to the [[kernel parameters]] as {{ic|1=spl.spl_hostid=0x0a0af0f8}}. Another solution is writing the hostid inside the initram image, see the [[Installing Arch Linux on ZFS#After the first boot|installation guide]]{{Broken section link}} explanation about this.<br />
<br />
Users can always ignore the check adding {{ic|1=zfs_force=1}} in the [[kernel parameters]], but it is not advisable as a permanent solution.<br />
<br />
=== Devices have different sector alignment ===<br />
<br />
Once a drive has become faulted it should be replaced A.S.A.P. with an identical drive.<br />
<br />
# zpool replace bigdata ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-1CH166_W1F478BD -f<br />
<br />
but in this instance, the following error is produced:<br />
<br />
cannot replace ata-ST3000DM001-9YN166_S1F0KDGY with ata-ST3000DM001-1CH166_W1F478BD: devices have different sector alignment<br />
<br />
ZFS uses the ashift option to adjust for physical block size. When replacing the faulted disk, ZFS is attempting to use {{ic|<nowiki>ashift=12</nowiki>}}, but the faulted disk is using a different ashift (probably {{ic|<nowiki>ashift=9</nowiki>}}) and this causes the resulting error. <br />
<br />
For Advanced Format Disks with 4KB blocksize, an ashift of 12 is recommended for best performance. See [https://github.com/zfsonlinux/zfs/wiki/faq#performance-considerations 1.10 What’s going on with performance?] and [http://wiki.illumos.org/display/illumos/ZFS+and+Advanced+Format+disks ZFS and Advanced Format disks].<br />
<br />
Use zdb to find the ashift of the zpool: {{ic|zdb | grep ashift}}, then use the {{ic|-o}} argument to set the ashift of the replacement drive:<br />
<br />
# zpool replace bigdata ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-1CH166_W1F478BD -o ashift=9 -f<br />
<br />
Check the zpool status for confirmation:<br />
<br />
{{hc|# zpool status -v|<br />
pool: bigdata<br />
state: DEGRADED<br />
status: One or more devices is currently being resilvered. The pool will<br />
continue to function, possibly in a degraded state.<br />
action: Wait for the resilver to complete.<br />
scan: resilver in progress since Mon Jun 16 11:16:28 2014<br />
10.3G scanned out of 5.90T at 81.7M/s, 20h59m to go<br />
2.57G resilvered, 0.17% done<br />
config:<br />
<br />
NAME STATE READ WRITE CKSUM<br />
bigdata DEGRADED 0 0 0<br />
raidz1-0 DEGRADED 0 0 0<br />
replacing-0 OFFLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KDGY OFFLINE 0 0 0<br />
ata-ST3000DM001-1CH166_W1F478BD ONLINE 0 0 0 (resilvering)<br />
ata-ST3000DM001-9YN166_S1F0JKRR ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KBP8 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JTM1 ONLINE 0 0 0<br />
<br />
errors: No known data errors<br />
}}<br />
<br />
=== Pool resilvering stuck/restarting/slow? ===<br />
<br />
According to the ZFSonLinux github it is a known issue since 2012 with ZFS-ZED which causes the resilvering process to constantly restart, sometimes get stuck and be generally slow for some hardware. The simplest mitigation is to stop zfs-zed.service until the resilver completes<br />
<br />
=== Fix slow boot caused by failed import of unavailable pools in the initramfs zpool.cache ===<br />
<br />
Your boot time can be significantly impacted if you update your intitramfs (eg when doing a kernel update) when you have additional but non-permanently attached pools imported because these pools will get added to your initramfs zpool.cache and ZFS will attempt to import these extra pools on every boot, regardless of whether you have exported it and removed it from your regular zpool.cache.<br />
<br />
If you notice ZFS trying to import unavailable pools at boot, first run:<br />
<br />
$ zdb -C<br />
<br />
To check your zpool.cache for pools you do not want imported at boot. If this command is showing (a) additional, currently unavailable pool(s), run:<br />
<br />
# zpool set cachefile=/etc/zfs/zpool.cache zroot<br />
<br />
To clear the zpool.cache of any pools other than the pool named zroot. Sometimes there is no need to refresh your zpool.cache, but instead all you need to do is [[regenerate the initramfs]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Embed the archzfs packages into an archiso ===<br />
<br />
Follow the [[Archiso]] steps for creating a fully functional Arch Linux live CD/DVD/USB image.<br />
<br />
Enable the [[Unofficial user repositories#archzfs|archzfs]] repository:<br />
<br />
{{hc|~/archlive/pacman.conf|<nowiki><br />
...<br />
[archzfs]<br />
Server = http://archzfs.com/$repo/x86_64<br />
SigLevel = Optional TrustAll<br />
</nowiki>}}<br />
<br />
Add the {{ic|archzfs-linux}} group to the list of packages to be installed (the {{ic|archzfs}} repository provides packages for the x86_64 architecture only).<br />
<br />
{{hc|~/archlive/packages.x86_64|<br />
...<br />
archzfs-linux<br />
}}<br />
<br />
Complete [[Archiso#Build_the_ISO|Build the ISO]] to finally build the iso.<br />
<br />
{{Note|If you later have problems running modprobe zfs, you should include the linux-headers in the packages.x86_64. }}<br />
<br />
=== Automatic snapshots ===<br />
<br />
==== ZFS Automatic Snapshot Service for Linux ====<br />
<br />
The {{AUR|zfs-auto-snapshot-git}} package from [[AUR]] provides a shell script to automate the management of snapshots, with each named by date and label (hourly, daily, etc), giving quick and convenient snapshotting of all ZFS datasets. The package also installs cron tasks for quarter-hourly, hourly, daily, weekly, and monthly snapshots. Optionally adjust the {{ic|--keep parameter}} from the defaults depending on how far back the snapshots are to go (the monthly script by default keeps data for up to a year).<br />
<br />
To prevent a dataset from being snapshotted at all, set {{ic|1=com.sun:auto-snapshot=false}} on it. Likewise, set more fine-grained control as well by label, if, for example, no monthlies are to be kept on a snapshot, for example, set {{ic|1=com.sun:auto-snapshot:monthly=false}}.<br />
<br />
{{Note|zfs-auto-snapshot-git will not create snapshots during [[#Scrubbing|scrubbing]]. It is possible to override this by [[Systemd#Editing provided units|editing provided systemd unit]] and removing `--skip-scrub` from `ExecStart` line. Consequences not known, someone please edit.}}<br />
<br />
Once the package has been installed, [[systemd/Timers|enable and start the selected timers]] ({{ic|<nowiki>zfs-auto-snapshot-{frequent,daily,weekly,monthly}.timer</nowiki>}}).<br />
<br />
==== ZFS Snapshot Manager ====<br />
<br />
The {{AUR|zfs-snap-manager}} package from [[AUR]] provides a python service that takes daily snapshots from a configurable set of ZFS datasets and cleans them out in a [[wikipedia:Backup rotation scheme#Grandfather-father-son|"Grandfather-father-son"]] scheme. It can be configured to e.g. keep 7 daily, 5 weekly, 3 monthly and 2 yearly snapshots. <br />
<br />
The package also supports configurable replication to other machines running ZFS by means of {{ic|zfs send}} and {{ic|zfs receive}}. If the destination machine runs this package as well, it could be configured to keep these replicated snapshots for a longer time. This allows a setup where a source machine has only a few daily snapshots locally stored, while on a remote storage server a much longer retention is available.<br />
<br />
==== zrepl ====<br />
<br />
The {{AUR|zrepl}} package from the [[AUR]] provides a ZFS automatic replication service, which could also be used as a snapshotting service much like [[snapper]].<br />
<br />
For details on how to configure the zrepl daemon, see the zrepl [https://zrepl.github.io/ documentation]. The configuration file should be located at {{ic|/etc/zrepl/zrepl.yml}}. Then, run {{ic|zrepl configcheck}} to make sure that the syntax of the config file is correct. Finally, enable {{ic|zrepl.service}}.<br />
<br />
=== Creating a share ===<br />
<br />
ZFS has support for creating shares by [[NFS]] or [[SMB]].<br />
<br />
==== NFS ====<br />
<br />
Make sure [[NFS]] has been installed/configured, note there is no need to edit the {{ic|/etc/exports}} file. For sharing over NFS the services {{ic|nfs-server.service}} and {{ic|zfs-share.service}} should be [[start|started]].<br />
<br />
To make a pool available on the network:<br />
<br />
# zfs set sharenfs=on <nameofzpool><br />
<br />
To make a dataset available on the network:<br />
<br />
# zfs set sharenfs=on <nameofzpool>/<nameofdataset><br />
<br />
To enable read/write access for a specific ip-range(s):<br />
<br />
# zfs set sharenfs="rw=@192.168.1.100/24,rw=@10.0.0.0/24" <nameofzpool>/<nameofdataset><br />
<br />
To check if the dataset is exported successful:<br />
<br />
{{hc|# showmount -e `hostname`|<br />
Export list for hostname:<br />
/path/of/dataset 192.168.1.100/24<br />
}}<br />
<br />
To view the current loaded exports state in more detail, use:<br />
<br />
{{hc|# exportfs -v|2=<br />
/path/of/dataset<br />
192.168.1.100/24(sync,wdelay,hide,no_subtree_check,mountpoint,sec=sys,rw,secure,no_root_squash,no_all_squash)<br />
}}<br />
<br />
==== SMB ====<br />
<br />
When sharing smb shares configuring usershares in your smb.conf will allow ZFS to setup and create the shares.<br />
<br />
{{bc|1=<br />
# [global]<br />
# usershare path = /var/lib/samba/usershares<br />
# usershare max shares = 100<br />
# usershare allow guests = yes<br />
# usershare owner only = no<br />
}}<br />
<br />
Create and set permissions on the user directory as root<br />
<br />
# mkdir /var/lib/samba/usershares<br />
# chmod +t /var/lib/samba/usershares<br />
<br />
To make a pool available on the network:<br />
<br />
# zfs set sharesmb=on <nameofzpool><br />
<br />
To make a dataset available on the network:<br />
<br />
# zfs set sharesmb=on <nameofzpool>/<nameofdataset><br />
<br />
To check if the dataset is exported successfully:<br />
<br />
{{hc|# smbclient -L localhost -U%|<br />
Sharename Type Comment<br />
--------- ---- -------<br />
IPC$ IPC IPC Service (SMB Server Name)<br />
<nameofzpool>_<nameofdataset> Disk Comment: path/of/dataset<br />
SMB1 disabled -- no workgroup available<br />
}}<br />
<br />
=== Encryption in ZFS using dm-crypt ===<br />
<br />
The stable release version of ZFS on Linux used to not support encryption directly (now it's available, see [[#Native encryption]]), but zpools can be created on dm-crypt block devices. Since the zpool is created on the plain-text abstraction, it is possible to have the data encrypted while having all the advantages of ZFS like deduplication, compression, and data robustness.<br />
<br />
dm-crypt, possibly via LUKS, creates devices in {{ic|/dev/mapper}} and their name is fixed. So you just need to change {{ic|zpool create}} commands to point to that names. The idea is configuring the system to create the {{ic|/dev/mapper}} block devices and import the zpools from there. Since zpools can be created in multiple devices (raid, mirroring, striping, ...), it is important all the devices are encrypted otherwise the protection might be partially lost.<br />
<br />
For example, an encrypted zpool can be created using plain dm-crypt (without LUKS) with:<br />
<br />
# cryptsetup --hash=sha512 --cipher=twofish-xts-plain64 --offset=0 \<br />
--key-file=/dev/sdZ --key-size=512 open --type=plain /dev/sdX enc<br />
# zpool create zroot /dev/mapper/enc<br />
<br />
In the case of a root filesystem pool, the {{ic|mkinitcpio.conf}} HOOKS line will enable the keyboard for the password, create the devices, and load the pools. It will contain something like:<br />
<br />
HOOKS="... keyboard encrypt zfs ..."<br />
<br />
Since the {{ic|/dev/mapper/enc}} name is fixed no import errors will occur.<br />
<br />
Creating encrypted zpools works fine. But if you need encrypted directories, for example to protect your users' homes, ZFS loses some functionality.<br />
<br />
ZFS will see the encrypted data, not the plain-text abstraction, so compression and deduplication will not work. The reason is that encrypted data has always high entropy making compression ineffective and even from the same input you get different output (thanks to salting) making deduplication impossible. To reduce the unnecessary overhead it is possible to create a sub-filesystem for each encrypted directory and use [[eCryptfs]] on it.<br />
<br />
For example to have an encrypted home: (the two passwords, encryption and login, must be the same)<br />
<br />
# zfs create -o compression=off -o dedup=off -o mountpoint=/home/<username> <zpool>/<username><br />
# useradd -m <username><br />
# passwd <username><br />
# ecryptfs-migrate-home -u <username><br />
<log in user and complete the procedure with ecryptfs-unwrap-passphrase><br />
<br />
=== Emergency chroot repair with archzfs ===<br />
<br />
To get into the ZFS filesystem from live system for maintenance, there are two options:<br />
<br />
# Build custom archiso with ZFS as described in [[#Embed the archzfs packages into an archiso]].<br />
# Boot the latest official archiso and bring up the network. Then enable [[Unofficial_user_repositories#archzfs|archzfs]] repository inside the live system as usual, sync the pacman package database and install the ''archzfs-archiso-linux'' package.<br />
<br />
To start the recovery, load the ZFS kernel modules:<br />
<br />
# modprobe zfs<br />
<br />
Import the pool:<br />
<br />
# zpool import -a -R /mnt<br />
<br />
Mount the boot partitions (if any):<br />
<br />
# mount /dev/sda2 /mnt/boot<br />
# mount /dev/sda1 /mnt/boot/efi<br />
<br />
Chroot into the ZFS filesystem:<br />
<br />
# arch-chroot /mnt /bin/bash<br />
<br />
Check the kernel version:<br />
<br />
# pacman -Qi linux<br />
# uname -r<br />
<br />
uname will show the kernel version of the archiso. If they are different, run depmod (in the chroot) with the correct kernel version of the chroot installation:<br />
<br />
# depmod -a 3.6.9-1-ARCH (version gathered from pacman -Qi linux but using the matching kernel modules directory name under the chroot's /lib/modules)<br />
<br />
This will load the correct kernel modules for the kernel version installed in the chroot installation.<br />
<br />
[[Regenerate the initramfs]]. There should be no errors.<br />
<br />
=== Bind mount ===<br />
<br />
Here a bind mount from /mnt/zfspool to /srv/nfs4/music is created. The configuration ensures that the zfs pool is ready before the bind mount is created.<br />
<br />
==== fstab ====<br />
<br />
See [https://www.freedesktop.org/software/systemd/man/systemd.mount.html systemd.mount] for more information on how systemd converts fstab into mount unit files with [https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html systemd-fstab-generator].<br />
<br />
{{hc|/etc/fstab|<nowiki><br />
/mnt/zfspool /srv/nfs4/music none bind,defaults,nofail,x-systemd.requires=zfs-mount.service 0 0<br />
</nowiki>}}<br />
<br />
=== Monitoring / Mailing on Events ===<br />
<br />
See [https://ramsdenj.com/2016/08/29/arch-linux-on-zfs-part-3-followup.html ZED: The ZFS Event Daemon] for more information.<br />
<br />
An email forwarder, such as [[S-nail]] (installed as part of {{Pkg|base}}), is required to accomplish this. Test it to be sure it is working correctly.<br />
<br />
Uncomment the following in the configuration file:<br />
<br />
{{hc|/etc/zfs/zed.d/zed.rc|<nowiki><br />
ZED_EMAIL_ADDR="root"<br />
ZED_EMAIL_PROG="mailx"<br />
ZED_NOTIFY_VERBOSE=0<br />
ZED_EMAIL_OPTS="-s '@SUBJECT@' @ADDRESS@"<br />
</nowiki>}}<br />
<br />
Update 'root' in {{ic|1=ZED_EMAIL_ADDR="root"}} to the email address you want to receive notifications at.<br />
<br />
If you are keeping your mailrc in your home directory, you can tell mail to get it from there by setting {{ic|MAILRC}}:<br />
<br />
{{hc|/etc/zfs/zed.d/zed.rc|2=<br />
export MAILRC=/home/<user>/.mailrc<br />
}}<br />
<br />
This works because ZED sources this file, so {{ic|mailx}} sees this environment variable.<br />
<br />
If you want to receive an email no matter the state of your pool, you will want to set {{ic|1=ZED_NOTIFY_VERBOSE=1}}. You will need to do this temporary to test.<br />
<br />
[[Start]] and [[enable]] {{ic|zfs-zed.service}}.<br />
<br />
With {{ic|1=ZED_NOTIFY_VERBOSE=1}}, you can test by running a scrub as root: {{ic|1=zpool scrub <pool-name>}}.<br />
<br />
=== Wrap shell commands in pre & post snapshots ===<br />
<br />
Since it is so cheap to make a snapshot, we can use this as a measure of security for sensitive commands such as system and package upgrades. If we make a snapshot before, and one after, we can later diff these snapshots to find out what changed on the filesystem after the command executed. Furthermore we can also rollback in case the outcome was not desired.<br />
<br />
E.g.:<br />
<br />
# zfs snapshot -r zroot@pre<br />
# pacman -Syu<br />
# zfs snapshot -r zroot@post<br />
# zfs diff zroot@pre zroot@post <br />
# zfs rollback zroot@pre<br />
<br />
A utility that automates the creation of pre and post snapshots around a shell command is [https://gist.github.com/erikw/eeec35be33e847c211acd886ffb145d5 znp].<br />
<br />
E.g.:<br />
<br />
# znp pacman -Syu<br />
# znp find / -name "something*" -delete<br />
<br />
and you would get snapshots created before and after the supplied command, and also output of the commands logged to file for future reference so we know what command created the diff seen in a pair of pre/post snapshots.<br />
<br />
=== Remote unlocking of ZFS encrypted root ===<br />
<br />
As of [https://github.com/archzfs/archzfs/pull/261 PR #261], {{ic|archzfs}} supports SSH unlocking of natively-encrypted ZFS datasets. This section describes how to use this feature, and is largely based on [[dm-crypt/Specialties#Remote unlocking (hooks: netconf, dropbear, tinyssh, ppp)]].<br />
<br />
#Install {{Pkg|mkinitcpio-netconf}} to provide hooks for setting up early user space networking.<br />
#Choose an SSH server to use in early user space. The options are {{Pkg|mkinitcpio-tinyssh}} or {{Pkg|mkinitcpio-dropbear}}, and are mutually exclusive.<br />
##If using {{Pkg|mkinitcpio-tinyssh}}, it is also recommended to install {{Pkg|tinyssh-convert}} or {{AUR|tinyssh-convert-git}}. This tool converts an existing OpenSSH hostkey to the TinySSH key format, preserving the key fingerprint and avoiding connection warnings. The TinySSH and Dropbear mkinitcpio install scripts will automatically convert existing hostkeys when generating a new initcpio image.<br />
#Decide whether to use an existing OpenSSH key or generate a new one (recommended) for the host that will be connecting to and unlocking the encrypted ZFS machine. Copy the public key into {{ic|/etc/tinyssh/root_key}} or {{ic|/etc/dropbear/root_key}}. When generating the initcpio image, this file will be added to {{ic|authorized_keys}} for the root user and is only valid in the initrd environment.<br />
#Add the {{ic|1=ip=}} [[kernel parameter]] to your boot loader configuration. The {{ic|ip}} string is [https://www.kernel.org/doc/html/latest/admin-guide/nfs/nfsroot.html highly configurable]. A simple DHCP example is shown below.{{bc|1=ip=:::::eth0:dhcp}}<br />
#Edit {{ic|/etc/mkinitcpio.conf}} to include the {{ic|netconf}}, {{ic|dropbear}} or {{ic|tinyssh}}, and {{ic|zfsencryptssh}} hooks before the {{ic|zfs}} hook:{{bc|1=HOOKS=(... netconf <tinyssh>{{!}}<dropbear> zfsencryptssh zfs ...)}}<br />
#[[Regenerate the initramfs]].<br />
#Reboot and try it out!<br />
<br />
====Changing the SSH server port====<br />
<br />
By default, {{Pkg|mkinitcpio-tinyssh}} and {{Pkg|mkinitcpio-dropbear}} listen on port {{ic|22}}. You may wish to change this.<br />
<br />
For '''TinySSH''', copy {{ic|/usr/lib/initcpio/hooks/tinyssh}} to {{ic|/etc/initcpio/hooks/tinyssh}}, and find/modify the following line in the {{ic|run_hook()}} function:<br />
<br />
{{hc|/etc/initcpio/hooks/tinyssh|<br />
/usr/bin/tcpserver -HRDl0 0.0.0.0 <new_port> /usr/sbin/tinysshd -v /etc/tinyssh/sshkeydir &<br />
}}<br />
<br />
For '''Dropbear''', copy {{ic|/usr/lib/initcpio/hooks/dropbear}} to {{ic|/etc/initcpio/hooks/dropbear}}, and find/modify the following line in the {{ic|run_hook()}} function:<br />
<br />
{{hc|/etc/initcpio/hooks/tinyssh|<br />
/usr/sbin/dropbear -E -s -j -k -p <new_port><br />
}}<br />
<br />
[[Regenerate the initramfs]].<br />
<br />
==== Unlocking from a Windows machine using PuTTY/Plink ====<br />
<br />
First, we need to use {{ic|puttygen.exe}} to import and convert the OpenSSH key generated earlier into PuTTY's ''.ppk'' private key format. Let us call it {{ic|zfs_unlock.ppk}} for this example.<br />
<br />
The mkinitcpio-netconf process above does not setup a shell (nor do we need need one). However, because there is no shell, PuTTY will immediately close after a successful connection. This can be disabled in the PuTTY SSH configuration (''Connection -> SSH -> [X] Do not start a shell or command at all''), but it still does not allow us to see stdout or enter the encryption passphrase. Instead, we use {{ic|plink.exe}} with the following parameters:<br />
<br />
plink.exe -ssh -l root -i c:\path\to\zfs_unlock.ppk <hostname><br />
<br />
The plink command can be put into a batch script for ease of use.<br />
<br />
== See also ==<br />
<br />
* [https://pthree.org/2012/12/04/zfs-administration-part-i-vdevs/ Aaron Toponce's 17-part blog on ZFS]<br />
* [http://zfsonlinux.org/ ZFS on Linux]<br />
* [https://github.com/zfsonlinux/zfs/wiki/faq ZFS on Linux FAQ]<br />
* [https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/zfs.html FreeBSD Handbook - The Z File System]<br />
* [https://docs.oracle.com/cd/E19253-01/819-5461/index.html Oracle Solaris ZFS Administration Guide]<br />
* [https://web.archive.org/web/20161028084224/http://www.solarisinternals.com/wiki/index.php/ZFS_Best_Practices_Guide ZFS Best Practices Guide]<br />
* [https://docs.oracle.com/cd/E23823_01/html/819-5461/gavwg.html ZFS Troubleshooting Guide]<br />
* [http://royal.pingdom.com/2013/06/04/zfs-backup/ How Pingdom uses ZFS to back up 5TB of MySQL data every day]<br />
* [https://www.linuxquestions.org/questions/linux-from-scratch-13/%5Bhow-to%5D-add-zfs-to-the-linux-kernel-4175514510/ Tutorial on adding the modules to a custom kernel]<br />
* [https://github.com/danboid/creating-ZFS-disks-under-Linux How to create cross platform ZFS disks under Linux]<br />
* [https://blog.heckel.xyz/2017/01/08/zfs-encryption-openzfs-zfs-on-linux/ How-To: Using ZFS Encryption at Rest in OpenZFS (ZFS on Linux, ZFS on FreeBSD, …)]</div>Ondrianhttps://wiki.archlinux.org/index.php?title=ZFS&diff=634838ZFS2020-09-10T08:02:50Z<p>Ondrian: /* ZFS is using too much RAM */ The arc_max settings is (silently) ignored in case that the arc_min default value exceeds the arc_max value.</p>
<hr />
<div>[[Category:File systems]]<br />
[[Category:Oracle]]<br />
[[ja:ZFS]]<br />
[[pt:ZFS]]<br />
[[zh-hans:ZFS]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related|ZFS/Virtual disks}}<br />
{{Related|Installing Arch Linux on ZFS}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:ZFS|ZFS]] is an advanced filesystem created by [[Wikipedia:Sun Microsystems|Sun Microsystems]] (now owned by Oracle) and released for OpenSolaris in November 2005. <br />
<br />
Features of ZFS include: pooled storage (integrated volume management – zpool), [[Wikipedia:Copy-on-write|Copy-on-write]], [[Wikipedia:Snapshot (computer storage)|snapshots]], data integrity verification and automatic repair (scrubbing), [[Wikipedia:RAID-Z|RAID-Z]], a maximum [[Wikipedia:Exabyte|16 Exabyte]] file size, and a maximum 256 Quadrillion [[Wikipedia:Zettabyte|Zettabytes]] storage with no limit on number of filesystems (datasets) or files[http://docs.oracle.com/cd/E19253-01/819-5461/zfsover-2/index.html]. ZFS is licensed under the [[Wikipedia:CDDL|Common Development and Distribution License]] (CDDL).<br />
<br />
Described as [https://web.archive.org/web/20060428092023/http://www.sun.com/2004-0914/feature/ "The last word in filesystems"] ZFS is stable, fast, secure, and future-proof. Being licensed under the CDDL, and thus incompatible with GPL, it is not possible for ZFS to be distributed along with the Linux Kernel. This requirement, however, does not prevent a native Linux kernel module from being developed and distributed by a third party, as is the case with [http://zfsonlinux.org/ zfsonlinux.org] (ZOL).<br />
<br />
ZOL is a project funded by the [https://www.llnl.gov/ Lawrence Livermore National Laboratory] to develop a native Linux kernel module for its massive storage requirements and super computers.<br />
<br />
{{Note|<br />
Due to potential legal incompatibilities between CDDL license of ZFS code and GPL of the Linux kernel ([https://sfconservancy.org/blog/2016/feb/25/zfs-and-linux/ ],[[wikipedia:Common_Development_and_Distribution_License#GPL_compatibility|CDDL-GPL]],[[wikipedia:ZFS#Linux|ZFS in Linux]]) - ZFS development is not supported by the kernel.<br />
<br />
As a result:<br />
<br />
* ZFSonLinux project must keep up with Linux kernel versions. After making stable ZFSonLinux release - Arch ZFS maintainers release them.<br />
* This situation sometimes locks down the normal rolling update process by unsatisfied dependencies because the new kernel version, proposed by update, is unsupported by ZFSonLinux.<br />
}}<br />
<br />
== Installation ==<br />
<br />
=== General ===<br />
<br />
{{Warning|Unless you use the [[dkms]] versions of these packages, the ZFS and SPL kernel modules are tied to a specific kernel version. It would not be possible to apply any kernel updates until updated packages are uploaded to AUR or the [[Unofficial user repositories#archzfs|archzfs]] repository.}}<br />
<br />
{{Tip| You can [[downgrade]] your linux version to the one from [[Unofficial user repositories#archzfs|archzfs]] repo if your current kernel is newer.}}<br />
<br />
Install from the [[Unofficial user repositories#archzfs|archzfs]] repository or alternatively the [[Arch User Repository]]:<br />
<br />
* {{AUR|zfs-linux}} for [http://zfsonlinux.org/ stable] releases.<br />
* {{AUR|zfs-linux-git}} for [https://github.com/zfsonlinux/zfs/releases development] releases (with support of newer kernel versions).<br />
* {{AUR|zfs-linux-lts}} for stable releases for LTS kernels.<br />
* {{AUR|zfs-linux-lts-git}} for development releases for LTS kernels.<br />
* {{AUR|zfs-linux-hardened}} for stable releases for hardened kernels.<br />
* {{AUR|zfs-linux-hardened-git}} for development releases for hardened kernels.<br />
* {{AUR|zfs-linux-zen}} for stable releases for zen kernels.<br />
* {{AUR|zfs-linux-zen-git}} for development releases for zen kernels.<br />
* {{AUR|zfs-dkms}} for versions with dynamic kernel module support.<br />
* {{AUR|zfs-dkms-git}} for development releases for versions with dynamic kernel module support.<br />
<br />
These branches have (according to them) dependency on the {{ic|zfs-utils}} package.<br />
<br />
Test the installation by issuing {{ic|zpool status}} on the command line. If an "insmod" error is produced, try {{ic|depmod -a}}.<br />
<br />
=== Root on ZFS ===<br />
<br />
See [[Install_Arch_Linux_on_ZFS#Installation|Installation]].<br />
<br />
=== DKMS ===<br />
<br />
Users can make use of DKMS [[Dynamic Kernel Module Support]] to rebuild the ZFS modules automatically with every kernel upgrade. <br />
<br />
Install {{AUR|zfs-dkms}} or {{AUR|zfs-dkms-git}} and apply the post-install instructions given by these packages.<br />
<br />
{{Tip|Add an {{ic|IgnorePkg}} entry to [[pacman.conf]] to prevent these packages from upgrading when doing a regular update.}}<br />
<br />
== Experimenting with ZFS ==<br />
<br />
Users wishing to experiment with ZFS on ''virtual block devices'' (known in ZFS terms as VDEVs) which can be simple files like {{ic|~/zfs0.img}} {{ic|~/zfs1.img}} {{ic|~/zfs2.img}} etc. with no possibility of real data loss are encouraged to see the [[Experimenting with ZFS]] article. Common tasks like building a RAIDZ array, purposefully corrupting data and recovering it, snapshotting datasets, etc. are covered.<br />
<br />
== Configuration ==<br />
<br />
ZFS is considered a "zero administration" filesystem by its creators; therefore, configuring ZFS is very straight forward. Configuration is done primarily with two commands: {{ic|zfs}} and {{ic|zpool}}.<br />
<br />
=== Automatic Start ===<br />
<br />
Currently, by default, the kernel module is not loaded at boot (see more details in https://github.com/zfsonlinux/zfs/issues/6083). To automatically load {{Ic|zfs}} module on boot, see [[Kernel module#Automatic module loading with systemd]].<br />
<br />
For ZFS to live by its "zero administration" namesake, {{Ic|zfs-import-cache.service}} must be enabled to import the pools and {{Ic|zfs-mount.service}} must be enabled to mount the filesystems available in the pools. A benefit to this is that it is not necessary to mount ZFS filesystems in {{ic|/etc/fstab}}. {{Ic|zfs-import-cache.service}} imports the zfs pools reading the file {{ic|/etc/zfs/zpool.cache}}.<br />
<br />
For each [[#Importing a pool created by id|imported pool]] you want automatically imported by {{Ic|zfs-import-cache.service}} execute:<br />
<br />
# zpool set cachefile=/etc/zfs/zpool.cache <pool><br />
<br />
{{Note|Beginning with ZOL version 0.6.5.8 the ZFS service unit files have been changed so that you need to explicitly enable any ZFS services you want to run. See [https://github.com/archzfs/archzfs/issues/72 https://github.com/archzfs/archzfs/issues/72] for more information.}}<br />
<br />
Enable the relevant service and target so the pools are automatically imported at boot time:<br />
<br />
# systemctl enable zfs-import-cache<br />
# systemctl enable zfs-import.target<br />
<br />
To mount the ZFS filesystems, you have 2 choices:<br />
* Enable the [[#Using zfs-mount.service|zfs-mount.service]]<br />
* Using [[#Using zfs-mount-generator|zfs-mount-generator]]<br />
<br />
==== Using zfs-mount.service ====<br />
<br />
In order to mount ZFS filesystems automatically on boot you need to enable the following services and targets:<br />
<br />
# systemctl enable zfs-mount<br />
# systemctl enable zfs.target<br />
<br />
==== Using zfs-mount-generator ====<br />
<br />
You can also use the zfs-mount-generator to create systemd mount units for your ZFS filesystems at boot. systemd will automatically mount the filesystems based on the mount units without having to use the {{Ic|zfs-mount.service}}. To do that, you need to:<br />
<br />
# Create the {{Ic|/etc/zfs/zfs-list.cache}} directory.<br />
# Enable the ZFS Event Daemon(ZED) script (called a ZEDLET) required to create a list of mountable ZFS filesystems. {{bc|# ln -s /usr/lib/zfs/zed.d/history_event-zfs-list-cacher.sh /etc/zfs/zed.d}}<br />
# Enable and start the ZFS Event Daemon. This service is responsible for running the script in the previous step. {{bc|# systemctl enable zfs-zed.service<br># systemctl enable zfs.target<br># systemctl start zfs-zed.service}}<br />
# You need to create an empty file named after your pool in {{Ic|/etc/zfs/zfs-list.cache}}. The ZEDLET will only update the list of filesystems if the file for the pool already exists. {{bc|# touch /etc/zfs/zfs-list.cache/<pool-name>}}<br />
# Check the contents of {{Ic|/etc/zfs/zfs-list.cache/<pool-name>}}. If it is empty, make sure that the {{Ic|zfs-zed.service}} is running and just change the canmount property of any of your ZFS filesystem by running: {{bc|1=zfs set canmount=off zroot/fs1}} This change causes ZFS to raise an event which is captured by ZED, which in turn runs the ZEDLET to update the file in {{Ic|/etc/zfs/zfs-list.cache}}. If the file in {{Ic|/etc/zfs/zfs-list.cache}} is updated, you can set the {{Ic|canmount}} property of the filesystem back by running: {{bc|1=zfs set canmount=on zroot/fs1}}<br />
You need to add a file in {{Ic|/etc/zfs/zfs-list.cache}} for each ZFS pool in your system. Make sure the pools are imported by enabling {{Ic|zfs-import-cache.service}} and {{Ic|zfs-import.target}} as [[#Automatic Start|explained above]].<br />
<br />
== Storage pools ==<br />
<br />
It is not necessary to partition the drives before creating the ZFS filesystem. It is recommended to point ZFS at an entire disk (ie. `/dev/sdx` rather than `/dev/sdx1`), which will [https://www.reddit.com/r/zfs/comments/667na0/zfs_on_raw_or_gpt/dgh0l9t/ automatically create a GPT partition table] and add an 8 MB reserved partition at the end of the disk for legacy bootloaders. However, you can specify a partition or a file within an existing filesystem, if you wish to create multiple volumes with different redundancy properties.<br />
<br />
{{Note|If some or all device have been used in a software RAID set it is paramount to [[mdadm#Prepare the devices|erase any old RAID configuration information]].}}<br />
<br />
{{Warning|For [[Advanced Format]] Disks with 4KB sector size, an ashift of 12 is recommended for best performance. Advanced Format disks emulate a sector size of 512 bytes for compatibility with legacy systems, this causes ZFS to sometimes use an ashift option number that is not ideal. Once the pool has been created, the only way to change the ashift option is to recreate the pool. Using an ashift of 12 would also decrease available capacity. See [https://github.com/zfsonlinux/zfs/wiki/faq#performance-considerations 1.10 What’s going on with performance?], [https://github.com/zfsonlinux/zfs/wiki/faq#advanced-format-disks 1.15 How does ZFS on Linux handle Advanced Format disks?], and [http://wiki.illumos.org/display/illumos/ZFS+and+Advanced+Format+disks ZFS and Advanced Format disks].}}<br />
<br />
=== Identify disks ===<br />
<br />
[https://github.com/zfsonlinux/zfs/wiki/faq#selecting-dev-names-when-creating-a-pool ZFS on Linux] recommends using device IDs when creating ZFS storage pools of less than 10 devices. Use [[Persistent block device naming#by-id and by-path]] to identify the list of drives to be used for ZFS pool. <br />
<br />
The disk IDs should look similar to the following:<br />
<br />
{{hc|$ ls -lh /dev/disk/by-id/|<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JKRR -> ../../sdc<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0JTM1 -> ../../sde<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KBP8 -> ../../sdd<br />
lrwxrwxrwx 1 root root 9 Aug 12 16:26 ata-ST3000DM001-9YN166_S1F0KDGY -> ../../sdb}}<br />
<br />
{{Warning|If you create zpools using device names (e.g. {{ic|/dev/sda}},{{ic|/dev/sdb}},...) ZFS might not be able to detect zpools intermittently on boot.}}<br />
<br />
==== Using GPT labels ====<br />
<br />
{{Style|Missing references to [[Persistent block device naming]], it is useless to explain the differences (or even what they are) here.}}<br />
<br />
Disk labels and UUID can also be used for ZFS mounts by using [[GUID Partition Table|GPT]] partitions. ZFS drives have labels but Linux is unable to read them at boot. Unlike [[Master Boot Record|MBR]] partitions, GPT partitions directly support both UUID and labels independent of the format inside the partition. Partitioning rather than using the whole disk for ZFS offers two additional advantages. The OS does not generate bogus partition numbers from whatever unpredictable data ZFS has written to the partition sector, and if desired, you can easily over provision SSD drives, and slightly over provision spindle drives to ensure that different models with slightly different sector counts can zpool replace into your mirrors. This is a lot of organization and control over ZFS using readily available tools and techniques at almost zero cost.<br />
<br />
Use [[GUID Partition Table|gdisk]] to partition the all or part of the drive as a single partition. gdisk does not automatically name partitions so if partition labels are desired use gdisk command "c" to label the partitions. Some reasons you might prefer labels over UUID are: labels are easy to control, labels can be titled to make the purpose of each disk in your arrangement readily apparent, and labels are shorter and easier to type. These are all advantages when the server is down and the heat is on. GPT partition labels have plenty of space and can store most international characters [[wikipedia:GUID_Partition_Table#Partition_entries]] allowing large data pools to be labeled in an organized fashion.<br />
<br />
Drives partitioned with GPT have labels and UUID that look like this. <br />
<br />
{{hc|$ ls -l /dev/disk/by-partlabel|<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 zfsdata1 -> ../../sdd1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 zfsdata2 -> ../../sdc1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:59 zfsl2arc -> ../../sda1}}<br />
<br />
{{hc|$ ls -l /dev/disk/by-partuuid|<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 148c462c-7819-431a-9aba-5bf42bb5a34e -> ../../sdd1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:59 4f95da30-b2fb-412b-9090-fc349993df56 -> ../../sda1<br />
lrwxrwxrwx 1 root root 10 Apr 30 01:44 e5ccef58-5adf-4094-81a7-3bac846a885f -> ../../sdc1}}<br />
<br />
{{Tip|To minimize typing and copy/paste errors, set a local variable with the target PARTUUID: {{ic|<nowiki>$ UUID=$(lsblk --noheadings --output PARTUUID /dev/sd</nowiki>''XY''<nowiki>)</nowiki>}} }}<br />
<br />
=== Creating ZFS pools ===<br />
<br />
To create a ZFS pool:<br />
<br />
# zpool create -f -m <mount> <pool> [raidz(2|3)|mirror] <ids><br />
<br />
{{Tip|One may want to read [[#Advanced Format disks]] first as it may be recommend to set {{ic|ashift}} on pool creation.}}<br />
<br />
* '''create''': subcommand to create the pool.<br />
<br />
* '''-f''': Force creating the pool. This is to overcome the "EFI label error". See [[#Does not contain an EFI label]].<br />
<br />
* '''-m''': The mount point of the pool. If this is not specified, then the pool will be mounted to {{ic|/<pool>}}.<br />
<br />
* '''pool''': This is the name of the pool.<br />
<br />
* '''raidz(2|3)|mirror''': This is the type of virtual device that will be created from the pool of devices, raidz is a single disk of parity, raidz2 for 2 disks of parity and raidz3 for 3 disks of parity, similar to raid5 and raid6. Also available is '''mirror''', which is similar to raid1 or raid10, but is not constrained to just 2 device. If not specified, each device will be added as a vdev which is similar to raid0. After creation, a device can be added to each single drive vdev to turn it into a mirror, which can be useful for migrating data.<br />
<br />
* '''ids''': The [[Persistent_block_device_naming#by-id_and_by-path|ID's]] of the drives or partitions that to include into the pool.<br />
<br />
Create pool with single raidz vdev:<br />
<br />
# zpool create -f -m /mnt/data bigdata \<br />
raidz \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
Create pool with two mirror vdevs:<br />
<br />
# zpool create -f -m /mnt/data bigdata \<br />
mirror \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
mirror \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
==== Advanced Format disks ====<br />
<br />
At pool creation, '''ashift=12''' should always be used, except with SSDs that have 8k sectors where '''ashift=13''' is correct. A vdev of 512 byte disks using 4k sectors will not experience performance issues, but a 4k disk using 512 byte sectors will. Since '''ashift''' cannot be changed after pool creation, even a pool with only 512 byte disks should use 4k because those disks may need to be replaced with 4k disks or the pool may be expanded by adding a vdev composed of 4k disks. Because correct detection of 4k disks is not reliable, {{ic|<nowiki>-o ashift=12</nowiki>}} should always be specified during pool creation. See the [https://github.com/zfsonlinux/zfs/wiki/faq#advanced-format-disks ZFS on Linux FAQ] for more details.<br />
<br />
{{Tip|Use {{man|8|blockdev}} (part of {{Pkg|util-linux}}) to print the sector size reported by the device's ioctls: {{ic|blockdev --getpbsz /dev/sd''XY''}} as the root user.}}<br />
<br />
Create pool with ashift=12 and single raidz vdev:<br />
<br />
# zpool create -f -o ashift=12 -m /mnt/data bigdata \<br />
raidz \<br />
ata-ST3000DM001-9YN166_S1F0KDGY \<br />
ata-ST3000DM001-9YN166_S1F0JKRR \<br />
ata-ST3000DM001-9YN166_S1F0KBP8 \<br />
ata-ST3000DM001-9YN166_S1F0JTM1<br />
<br />
==== GRUB-compatible pool creation ====<br />
<br />
{{note|This section frequently goes out of date with updates to GRUB and ZFS. Consult the manual pages for the most up-to-date information.}}<br />
<br />
By default, ''zpool create'' enables all features on a pool. If {{ic|/boot}} resides on ZFS when using [[GRUB]] you must only enable features supported by GRUB otherwise GRUB will not be able to read the pool. GRUB 2.02 supports the read-write features {{ic|lz4_compress}}, {{ic|hole_birth}}, {{ic|embedded_data}}, {{ic|extensible_dataset}}, and {{ic|large_blocks}}; this is not suitable for all the features of ZFSonLinux 0.8.0, and must have unsupported features disabled. We can explicitly name features to enable with the {{ic|-d}} argument to {{ic|zpool create}}, which disables all features by default.<br />
<br />
You can create a pool with only the compatible features enabled:<br />
<br />
# zpool create -d -o feature@allocation_classes=enabled \<br />
-o feature@async_destroy=enabled \<br />
-o feature@bookmarks=enabled \<br />
-o feature@embedded_data=enabled \<br />
-o feature@empty_bpobj=enabled \<br />
-o feature@enabled_txg=enabled \<br />
-o feature@extensible_dataset=enabled \<br />
-o feature@filesystem_limits=enabled \<br />
-o feature@hole_birth=enabled \<br />
-o feature@large_blocks=enabled \<br />
-o feature@lz4_compress=enabled \<br />
-o feature@project_quota=enabled \<br />
-o feature@resilver_defer=enabled \<br />
-o feature@spacemap_histogram=enabled \<br />
-o feature@spacemap_v2=enabled \<br />
-o feature@userobj_accounting=enabled \<br />
-o feature@zpool_checkpoint=enabled \<br />
$POOL_NAME $VDEVS<br />
<br />
=== Verifying pool status ===<br />
<br />
If the command is successful, there will be no output. Using the [[mount]] command will show that the pool is mounted. Using {{ic|zpool status}} will show that the pool has been created:<br />
<br />
{{hc|# zpool status -v|<br />
pool: bigdata<br />
state: ONLINE<br />
scan: none requested<br />
config:<br />
<br />
NAME STATE READ WRITE CKSUM<br />
bigdata ONLINE 0 0 0<br />
-0 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KDGY-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JKRR-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KBP8-part1 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JTM1-part1 ONLINE 0 0 0<br />
<br />
errors: No known data errors<br />
}}<br />
<br />
At this point it would be good to reboot the machine to ensure that the ZFS pool is mounted at boot. It is best to deal with all errors before transferring data.<br />
<br />
=== Importing a pool created by id ===<br />
<br />
Eventually a pool may fail to auto mount and you need to import to bring your pool back. Take care to avoid the most obvious solution.<br />
<br />
{{Warning|Do not run {{ic|zpool import ''pool''}}! This will import your pools using {{ic|/dev/sd?}} which will lead to problems the next time you rearrange your drives. This may be as simple as rebooting with a USB drive left in the machine, which harkens back to a time when PCs would not boot when a floppy disk was left in a machine.}}<br />
<br />
Adapt one of the following commands to import your pool so that pool imports retain the persistence they were created with:<br />
<br />
# zpool import -d /dev/disk/by-id bigdata<br />
# zpool import -d /dev/disk/by-partlabel bigdata<br />
# zpool import -d /dev/disk/by-partuuid bigdata<br />
<br />
{{Note|Use the {{ic|-l}} flag when importing a pool that contains [[#Native encryption|encrypted datasets keys]]:<br />
# zpool import -l -d /dev/disk/by-id bigdata<br />
}}<br />
<br />
Finally check the state of the pool:<br />
<br />
# zpool status -v bigdata<br />
<br />
=== Destroy a storage pool ===<br />
<br />
ZFS makes it easy to destroy a mounted storage pool, removing all metadata about the ZFS device.<br />
<br />
{{Warning|This command destroys '''any data''' containing in the pool and/or dataset.}}<br />
<br />
To destroy the pool:<br />
# zpool destroy <pool><br />
<br />
To destroy a dataset:<br />
# zfs destroy <pool>/<dataset><br />
<br />
And now when checking the status:<br />
<br />
{{hc|# zpool status|<br />
no pools available<br />
}}<br />
<br />
=== Exporting a storage pool ===<br />
<br />
If a storage pool is to be used on another system, it will first need to be exported. It is also necessary to export a pool if it has been imported from the archiso as the hostid is different in the archiso as it is in the booted system. The zpool command will refuse to import any storage pools that have not been exported. It is possible to force the import with the {{ic|-f}} argument, but this is considered bad form.<br />
<br />
Any attempts made to import an un-exported storage pool will result in an error stating the storage pool is in use by another system. This error can be produced at boot time abruptly abandoning the system in the busybox console and requiring an archiso to do an emergency repair by either exporting the pool, or adding the {{ic|zfs_force&#61;1}} to the kernel boot parameters (which is not ideal). See [[#On boot the zfs pool does not mount stating: "pool may be in use from other system"]]<br />
<br />
To export a pool:<br />
<br />
# zpool export <pool><br />
<br />
=== Extending an existing zpool ===<br />
<br />
A device (a partition or a disk) can be added to an existing zpool:<br />
<br />
# zpool add <pool> <device-id><br />
<br />
To import a pool which consists of multiple devices:<br />
<br />
# zpool import -d <device-id-1> -d <device-id-2> <pool><br />
<br />
or simply:<br />
<br />
# zpool import -d /dev/disk-by-id/ <pool><br />
<br />
=== Renaming a zpool ===<br />
<br />
Renaming a zpool that is already created is accomplished in 2 steps:<br />
<br />
# zpool export oldname<br />
# zpool import oldname newname<br />
<br />
=== Setting a different mount point ===<br />
<br />
The mount point for a given zpool can be moved at will with one command:<br />
# zfs set mountpoint=/foo/bar poolname<br />
<br />
== Creating datasets ==<br />
<br />
Users can optionally create a dataset under the zpool as opposed to manually creating directories under the zpool. Datasets allow for an increased level of control (quotas for example) in addition to snapshots. To be able to create and mount a dataset, a directory of the same name must not pre-exist in the zpool. To create a dataset, use:<br />
<br />
# zfs create <nameofzpool>/<nameofdataset><br />
<br />
It is then possible to apply ZFS specific attributes to the dataset. For example, one could assign a quota limit to a specific directory within a dataset:<br />
<br />
# zfs set quota=20G <nameofzpool>/<nameofdataset>/<directory><br />
<br />
To see all the commands available in ZFS, see {{man|8|zfs|url=}} or {{man|8|zpool|url=}}.<br />
<br />
=== Native encryption ===<br />
<br />
ZFS offers the following supported encryption options: {{ic|aes-128-ccm}}, {{ic|aes-192-ccm}}, {{ic|aes-256-ccm}}, {{ic|aes-128-gcm}}, {{ic|aes-192-gcm}} and {{ic|aes-256-gcm}}. When encryption is set to {{ic|on}}, {{ic|aes-256-gcm}} will be used.<br />
<br />
The following keyformats are supported: {{ic|passphrase}}, {{ic|raw}}, {{ic|hex}}.<br />
<br />
One can also specify/increase the default iterations of PBKDF2 when using {{ic|passphrase}} with {{ic|-o pbkdf2iters <n>}}, although it may increase the decryption time.<br />
<br />
{{Note|<br />
* Native ZFS encryption has been made available in the stable 0.8.0 release or newer. Previously it was only available in development versions provided by packages like {{AUR|zfs-linux-git}}, {{AUR|zfs-dkms-git}} or other development builds. Users who were only using the development versions for the native encryption, may now switch to the stable releases if they wish.<br />
* The default encryption suite was changed from {{ic|aes-256-ccm}} to {{ic|aes-256-gcm}} in the 0.8.4 release.<br />
* To import a pool with keys, one needs to specify the {{ic|-l}} flag, without this flag encrypted datasets will be left unavailable until the keys are loaded. See [[#Importing a pool created by id]].}}<br />
<br />
To create a dataset including native encryption with a passphrase, use:<br />
<br />
# zfs create -o encryption=on -o keyformat=passphrase <nameofzpool>/<nameofdataset><br />
<br />
To use a key instead of using a passphrase:<br />
<br />
# dd if=/dev/random of=/path/to/key bs=1 count=32<br />
# zfs create -o encryption=on -o keyformat=raw -o keylocation=file:///path/to/key <nameofzpool>/<nameofdataset><br />
<br />
To verify the key location:<br />
# zfs get keylocation <nameofzpool>/<nameofdataset><br />
<br />
To change the key location:<br />
<br />
# zfs set keylocation=file:///path/to/key <nameofzpool>/<nameofdataset><br />
<br />
You can also manually load the keys by using one of the following commands:<br />
<br />
# zfs load-key <nameofzpool>/<nameofdataset> # load key for a specific dataset<br />
# zfs load-key -a # load all keys<br />
# zfs load-key -r zpool/dataset # load all keys in a dataset<br />
<br />
To mount the created encrypted dataset:<br />
<br />
# zfs mount <nameofzpool>/<nameofdataset><br />
<br />
==== Unlock at boot time ====<br />
It is possible to automatically unlock a pool dataset on boot time by using a [[systemd]] unit. For example create the following service to unlock any specific dataset: <br />
<br />
{{hc|/etc/systemd/system/zfs-load-key@.service|2=<br />
[Unit]<br />
Description=Load %I encryption keys<br />
Before=systemd-user-sessions.service<br />
After=zfs-import.target<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/bash -c 'until (systemd-ask-password "Encrypted ZFS password for %I" --no-tty <nowiki>|</nowiki> zfs load-key %I); do echo "Try again!"; done'<br />
<br />
[Install]<br />
WantedBy=zfs-mount.service<br />
}}<br />
<br />
[[Enable]]/[[start]] the service for each encrypted dataset, e.g. {{ic|systemctl enable zfs-load-key@pool0-dataset0}} as the root user. Note the use of {{ic|-}}, which is an escaped {{ic|/}} in systemd unit definitions. See {{ic|systemd-escape(1)}} for more info.<br />
{{Note|The {{ic|1=Before=systemd-user-sessions.service}} ensures that systemd-ask-password is invoked before the local IO devices are handed over to the [[desktop environment]].}}<br />
<br />
An alternative is to load all possible keys:<br />
<br />
{{hc|/etc/systemd/system/zfs-load-key.service|2=<br />
[Unit]<br />
Description=Load encryption keys<br />
DefaultDependencies=no<br />
After=zfs-import.target<br />
Before=zfs-mount.service<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=/usr/bin/bash -c '/usr/bin/zfs load-key -a'<br />
<br />
[Install]<br />
WantedBy=zfs-mount.service<br />
}}<br />
<br />
[[Enable]]/[[start]] {{ic|zfs-load-key.service}}.<br />
<br />
=== Swap volume ===<br />
<br />
{{Warning|On systems with extremely high memory pressure, using a zvol for swap can result in lockup, regardless of how much swap is still available. This issue is currently being investigated in https://github.com/zfsonlinux/zfs/issues/7734}}<br />
<br />
ZFS does not allow to use swapfiles, but users can use a ZFS volume (ZVOL) as swap. It is important to set the ZVOL block size to match the system page size, which can be obtained by the {{ic|getconf PAGESIZE}} command (default on x86_64 is 4KiB). Another option useful for keeping the system running well in low-memory situations is not caching the ZVOL data.<br />
<br />
Create a 8 GiB zfs volume:<br />
<br />
# zfs create -V 8G -b $(getconf PAGESIZE) -o compression=zle \<br />
-o logbias=throughput -o sync=always\<br />
-o primarycache=metadata -o secondarycache=none \<br />
-o com.sun:auto-snapshot=false <pool>/swap<br />
<br />
Prepare it as swap partition:<br />
<br />
# mkswap -f /dev/zvol/<pool>/swap<br />
# swapon /dev/zvol/<pool>/swap<br />
<br />
To make it permanent, edit {{ic|/etc/fstab}}. ZVOLs support discard, which can potentially help ZFS's block allocator and reduce fragmentation for all other datasets when/if swap is not full.<br />
<br />
Add a line to {{ic|/etc/fstab}}:<br />
<br />
/dev/zvol/<pool>/swap none swap discard 0 0<br />
<br />
=== Access Control Lists ===<br />
<br />
To use [[ACL]] on a dataset:<br />
<br />
# zfs set acltype=posixacl <nameofzpool>/<nameofdataset><br />
# zfs set xattr=sa <nameofzpool>/<nameofdataset><br />
<br />
Setting {{ic|xattr}} is recommended for performance reasons [https://github.com/zfsonlinux/zfs/issues/170#issuecomment-27348094].<br />
<br />
It may be preferable to enable ACL on the zpool as datasets will inherit the ACL parameters. Setting {{ic|1=aclinherit=passthrough}} may be wanted as the default mode is {{ic|restricted}} [https://docs.oracle.com/cd/E19120-01/open.solaris/817-2271/gbaaz/index.html]:<br />
<br />
# zfs set aclinherit=passthrough <nameofzpool><br />
# zfs set acltype=posixacl <nameofzpool><br />
# zfs set xattr=sa <nameofzpool><br />
<br />
=== Databases ===<br />
<br />
ZFS, unlike most other file systems, has a variable record size, or what is commonly referred to as a block size. By default, the recordsize on ZFS is 128KiB, which means it will dynamically allocate blocks of any size from 512B to 128KiB depending on the size of file being written. This can often help fragmentation and file access, at the cost that ZFS would have to allocate new 128KiB blocks each time only a few bytes are written to.<br />
<br />
Most RDBMSes work in 8KiB-sized blocks by default. Although the block size is tunable for [[MySQL|MySQL/MariaDB]], [[PostgreSQL]], and [[Oracle Database]], all three of them use an 8KiB block size ''by default''. For both performance concerns and keeping snapshot differences to a minimum (for backup purposes, this is helpful), it is usually desirable to tune ZFS instead to accommodate the databases, using a command such as:<br />
<br />
# zfs set recordsize=8K <pool>/postgres<br />
<br />
These RDBMSes also tend to implement their own caching algorithm, often similar to ZFS's own ARC. In the interest of saving memory, it is best to simply disable ZFS's caching of the database's file data and let the database do its own job:<br />
<br />
# zfs set primarycache=metadata <pool>/postgres<br />
<br />
If your pool has no configured log devices, ZFS reserves space on the pool's data disks for its intent log (the ZIL). ZFS uses this for crash recovery, but databases are often syncing their data files to the file system on their own transaction commits anyway. The end result of this is that ZFS will be committing data '''twice''' to the data disks, and it can severely impact performance. You can tell ZFS to prefer to not use the ZIL, and in which case, data is only committed to the file system once. Setting this for non-database file systems, or for pools with configured log devices, can actually ''negatively'' impact the performance, so beware:<br />
<br />
# zfs set logbias=throughput <pool>/postgres<br />
<br />
These can also be done at file system creation time, for example:<br />
<br />
# zfs create -o recordsize=8K \<br />
-o primarycache=metadata \<br />
-o mountpoint=/var/lib/postgres \<br />
-o logbias=throughput \<br />
<pool>/postgres<br />
<br />
Please note: these kinds of tuning parameters are ideal for specialized applications like RDBMSes. You can easily ''hurt'' ZFS's performance by setting these on a general-purpose file system such as your /home directory.<br />
<br />
=== /tmp ===<br />
<br />
If you would like to use ZFS to store your /tmp directory, which may be useful for storing arbitrarily-large sets of files or simply keeping your RAM free of idle data, you can generally improve performance of certain applications writing to /tmp by disabling file system sync. This causes ZFS to ignore an application's sync requests (eg, with {{ic|fsync}} or {{ic|O_SYNC}}) and return immediately. While this has severe application-side data consistency consequences (never disable sync for a database!), files in /tmp are less likely to be important and affected. Please note this does ''not'' affect the integrity of ZFS itself, only the possibility that data an application expects on-disk may not have actually been written out following a crash.<br />
<br />
# zfs set sync=disabled <pool>/tmp<br />
<br />
Additionally, for security purposes, you may want to disable '''setuid''' and '''devices''' on the /tmp file system, which prevents some kinds of privilege-escalation attacks or the use of device nodes:<br />
<br />
# zfs set setuid=off <pool>/tmp<br />
# zfs set devices=off <pool>/tmp<br />
<br />
Combining all of these for a create command would be as follows:<br />
<br />
# zfs create -o setuid=off -o devices=off -o sync=disabled -o mountpoint=/tmp <pool>/tmp<br />
<br />
Please note, also, that if you want /tmp on ZFS, you will need to mask (disable) [[systemd]]'s automatic tmpfs-backed /tmp, else ZFS will be unable to mount your dataset at boot-time or import-time:<br />
<br />
# systemctl mask tmp.mount<br />
<br />
== Tuning ==<br />
<br />
=== General ===<br />
<br />
ZFS pools and datasets can be further adjusted using parameters.<br />
<br />
{{Note|All settable properties, with the exception of quotas and reservations, inherit their value from the parent dataset.}}<br />
<br />
To retrieve the current pool parameter status:<br />
<br />
# zfs get all <pool><br />
<br />
To retrieve the current dataset parameter status:<br />
<br />
# zfs get all <pool>/<dataset><br />
<br />
To disable access time (atime), which is enabled by default:<br />
<br />
# zfs set atime=off <pool><br />
<br />
To disable access time (atime) on a particular dataset:<br />
<br />
# zfs set atime=off <pool>/<dataset><br />
<br />
An alternative to turning off atime completely, {{ic|relatime}} is available. This brings the default ext4/XFS atime semantics to ZFS, where access time is only updated if the modified time or changed time changes, or if the existing access time has not been updated within the past 24 hours. It is a compromise between {{ic|1=atime=off}} and {{ic|1=atime=on}}. This property ''only'' takes effect if {{ic|atime}} is {{ic|on}}:<br />
<br />
# zfs set atime=on <pool><br />
# zfs set relatime=on <pool><br />
<br />
Compression is just that, transparent compression of data. ZFS supports a few different algorithms, presently lz4 is the default, ''gzip'' is also available for seldom-written yet highly-compressible data; consult the [http://open-zfs.org/wiki/Performance_tuning#Compression OpenZFS Wiki] for more details. <br />
<br />
To enable compression:<br />
<br />
# zfs set compression=on <pool><br />
<br />
To reset a property of a pool and/or dataset to it's default state, use {{ic|zfs inherit}}:<br />
<br />
# zfs inherit -rS atime <pool><br />
# zfs inherit -rS atime <pool>/<dataset><br />
<br />
{{Warning|Using the {{ic|-r}} flag will recursively reset all datasets of the zpool.}}<br />
<br />
=== Scrubbing ===<br />
<br />
Whenever data is read and ZFS encounters an error, it is silently repaired when possible, rewritten back to disk and logged so you can obtain an overview of errors on your pools. There is no fsck or equivalent tool for ZFS. Instead, ZFS supports a feature known as scrubbing. This traverses through all the data in a pool and verifies that all blocks can be read.<br />
<br />
To scrub a pool:<br />
<br />
# zpool scrub <pool><br />
<br />
To cancel a running scrub:<br />
<br />
# zpool scrub -s <pool><br />
<br />
==== How often should I do this? ====<br />
<br />
From the Oracle blog post [https://blogs.oracle.com/wonders-of-zfs-storage/disk-scrub-why-and-when-v2 Disk Scrub - Why and When?]:<br />
<br />
:This question is challenging for Support to answer, because as always the true answer is "It Depends". So before I offer a general guideline, here are a few tips to help you create an answer more tailored to your use pattern.<br />
<br />
:* What is the expiration of your oldest backup? You should probably scrub your data at least as often as your oldest tapes expire so that you have a known-good restore point.<br />
:* How often are you experiencing disk failures? While the recruitment of a hot-spare disk invokes a "resilver" -- a targeted scrub of just the VDEV which lost a disk -- you should probably scrub at least as often as you experience disk failures on average in your specific environment.<br />
:* How often is the oldest piece of data on your disk read? You should scrub occasionally to prevent very old, very stale data from experiencing bit-rot and dying without you knowing it.<br />
<br />
:If any of your answers to the above are "I do not know", the general guideline is: you should probably be scrubbing your zpool at least once per month. It is a schedule that works well for most use cases, provides enough time for scrubs to complete before starting up again on all but the busiest & most heavily-loaded systems, and even on very large zpools (192+ disks) should complete fairly often between disk failures.<br />
<br />
In the [https://pthree.org/2012/12/11/zfs-administration-part-vi-scrub-and-resilver/ ZFS Administration Guide] by Aaron Toponce, he advises to scrub consumer disks once a week.<br />
<br />
==== Start with a service or timer ====<br />
Using a [[systemd]] timer/service it is possible to automatically scrub pools.<br />
<br />
To perform scrubbing monthly on a particular pool:<br />
<br />
{{hc|/etc/systemd/system/zfs-scrub@.timer|2=<br />
[Unit]<br />
Description=Monthly zpool scrub on %i<br />
<br />
[Timer]<br />
OnCalendar=monthly<br />
AccuracySec=1h<br />
Persistent=true<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/zfs-scrub@.service|2=<br />
[Unit]<br />
Description=zpool scrub on %i<br />
<br />
[Service]<br />
Nice=19<br />
IOSchedulingClass=idle<br />
KillSignal=SIGINT<br />
ExecStart=/usr/bin/zpool scrub %i<br />
}}<br />
<br />
[[Enable]]/[[start]] {{ic|zfs-scrub@''pool-to-scrub''.timer}} unit for monthly scrubbing the specified zpool.<br />
<br />
=== SSD Caching ===<br />
<br />
You can add SSD devices as a write intent log (external ZIL or SLOG) and also as a layer 2 adaptive replacement cache (L2ARC). The process to add them is very similar to adding a new VDEV.<br />
<br />
All of the below references to device-id are the IDs from {{ic|/dev/disk/by-id/*}}.<br />
<br />
==== SLOG ====<br />
<br />
To add a mirrored SLOG:<br />
<br />
# zpool add <pool> log mirror <device-id-1> <device-id-2><br />
<br />
Or to add a single device SLOG (unsafe):<br />
<br />
# zpool add <pool> log <device-id><br />
<br />
Because the SLOG device stores data that has not been written to the pool, it is important to use devices that can finish writes when power is lost. It is also important to use redundancy, since a device failure can cause data loss. In addition, the SLOG is only used for sync writes, so may not provide any performance improvement.<br />
<br />
==== L2ARC ====<br />
<br />
To add L2ARC:<br />
<br />
# zpool add <pool> cache <device-id><br />
<br />
Because every block cached in L2ARC uses a small amount of memory, it is generally only useful in workloads where the amount of hot data is *bigger* than the maximum amount of memory that can fit in the computer, but small enough to fit into L2ARC. It is also cleared at reboot and is only a read cache, so redundancy is unnecessary. Un-intuitively, L2ARC can actually harm performance since it takes memory away from ARC.<br />
<br />
=== ZVOLs ===<br />
<br />
ZFS volumes (ZVOLs) can suffer from the same block size-related issues as RDBMSes, but it is worth noting that the default recordsize for ZVOLs is 8 KiB already. If possible, it is best to align any partitions contained in a ZVOL to your recordsize (current versions of fdisk and gdisk by default automatically align at 1MiB segments, which works), and file system block sizes to the same size. Other than this, you might tweak the '''recordsize''' to accommodate the data inside the ZVOL as necessary (though 8 KiB tends to be a good value for most file systems, even when using 4 KiB blocks on that level).<br />
<br />
==== RAIDZ and Advanced Format physical disks ====<br />
<br />
Each block of a ZVOL gets its own parity disks, and if you have physical media with logical block sizes of 4096B, 8192B, or so on, the parity needs to be stored in whole physical blocks, and this can drastically increase the space requirements of a ZVOL, requiring 2× or more physical storage capacity than the ZVOL's logical capacity. Setting the '''recordsize''' to 16k or 32k can help reduce this footprint drastically.<br />
<br />
See [https://github.com/zfsonlinux/zfs/issues/1807 ZFS on Linux issue #1807 for details]<br />
<br />
=== I/O Scheduler ===<br />
<br />
When the pool is imported, for whole disk vdevs, the block device I/O scheduler is set to {{ic|zfs_vdev_scheduler}} [https://github.com/zfsonlinux/zfs/wiki/ZFS-on-Linux-Module-Parameters#zfs_vdev_scheduler]. The most common schedulers are: ''noop'', ''cfq'', ''bfq'', and ''deadline''.<br />
<br />
In some cases, the scheduler is not changeable using this method. Known schedulers that cannot be changed are: ''scsi_mq'' and ''none''. In these cases, the scheduler is unchanged and an error message can be reported to logs. [[Improving_performance#Changing_I/O_scheduler|Manually setting]] one of the common schedulers used by {{ic|zfs_vdev_scheduler}} can result in more consistent performance.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Creating a zpool fails ===<br />
<br />
If the following error occurs then it can be fixed.<br />
<br />
# the kernel failed to rescan the partition table: 16<br />
# cannot label 'sdc': try using parted(8) and then provide a specific slice: -1<br />
<br />
One reason this can occur is because [https://github.com/zfsonlinux/zfs/issues/2582 ZFS expects pool creation to take less than 1 second]. This is a reasonable assumption under ordinary conditions, but in many situations it may take longer. Each drive will need to be cleared again before another attempt can be made.<br />
<br />
# parted /dev/sda rm 1<br />
# parted /dev/sda rm 1<br />
# dd if=/dev/zero of=/dev/sdb bs=512 count=1<br />
# zpool labelclear /dev/sda<br />
<br />
A brute force creation can be attempted over and over again, and with some luck the ZPool creation will take less than 1 second.<br />
Once cause for creation slowdown can be slow burst read writes on a drive. By reading from the disk in parallell to ZPool creation, it may be possible to increase burst speeds.<br />
<br />
# dd if=/dev/sda of=/dev/null<br />
<br />
This can be done with multiple drives by saving the above command for each drive to a file on separate lines and running <br />
<br />
# cat $FILE | parallel<br />
<br />
Then run ZPool creation at the same time.<br />
<br />
=== ZFS is using too much RAM ===<br />
<br />
By default, ZFS caches file operations ([[wikipedia:Adaptive replacement cache|ARC]]) using up to two-thirds of available system memory on the host. To adjust the ARC size, add the following to the [[Kernel parameters]] list:<br />
<br />
zfs.zfs_arc_max=536870912 # (for 512MB)<br />
<br />
In case that the default value of {{ic|zfs_arc_min}} (1/32 of system memory) is higher that the specified {{ic|zfs_arc_max}} it is needed to add also the following to the [[Kernel parameters]] list:<br />
<br />
zfs.zfs_arc_min=268435456 # (for 256MB, needs to be lower than zfs.zfs_arc_max)<br />
<br />
For a more detailed description, as well as other configuration options, see [http://wiki.gentoo.org/wiki/ZFS#ARC gentoo-wiki:zfs#arc].<br />
<br />
=== Does not contain an EFI label ===<br />
<br />
The following error will occur when attempting to create a zfs filesystem,<br />
<br />
/dev/disk/by-id/<id> does not contain an EFI label but it may contain partition<br />
<br />
The way to overcome this is to use {{ic|-f}} with the zfs create command.<br />
<br />
=== No hostid found ===<br />
<br />
An error that occurs at boot with the following lines appearing before initscript output:<br />
<br />
ZFS: No hostid found on kernel command line or /etc/hostid.<br />
<br />
This warning occurs because the ZFS module does not have access to the spl hosted. There are two solutions, for this. Either place the spl hostid in the [[kernel parameters]] in the boot loader. For example, adding {{ic|1=spl.spl_hostid=0x00bab10c}}.<br />
<br />
The other solution is to make sure that there is a hostid in {{ic|/etc/hostid}}, and then [[regenerate the initramfs]] image. Which will copy the hostid into the initramfs image.<br />
<br />
=== Pool cannot be found while booting from SAS/SCSI devices ===<br />
<br />
In case you are booting a SAS/SCSI based, you might occassionally get boot problems where the pool you are trying to boot from cannot be found. A likely reason for this is that your devices are initialized too late into the process. That means that zfs cannot find any devices at the time when it tries to assemble your pool.<br />
<br />
In this case you should force the scsi driver to wait for devices to come online before continuing. You can do this by putting this into {{ic|/etc/modprobe.d/zfs.conf}}:<br />
<br />
{{hc|1=/etc/modprobe.d/zfs.conf|2=<br />
options scsi_mod scan=sync<br />
}}<br />
<br />
Afterwards, [[regenerate the initramfs]].<br />
<br />
This works because the zfs hook will copy the file at {{ic|/etc/modprobe.d/zfs.conf}} into the initcpio which will then be used at build time.<br />
<br />
=== On boot the zfs pool does not mount stating: "pool may be in use from other system" ===<br />
<br />
==== Unexported pool ====<br />
<br />
If the new installation does not boot because the zpool cannot be imported, chroot into the installation and properly export the zpool. See [[#Emergency chroot repair with archzfs]].<br />
<br />
Once inside the chroot environment, load the ZFS module and force import the zpool,<br />
<br />
# zpool import -a -f<br />
<br />
now export the pool:<br />
<br />
# zpool export <pool><br />
<br />
To see the available pools, use,<br />
<br />
# zpool status<br />
<br />
It is necessary to export a pool because of the way ZFS uses the hostid to track the system the zpool was created on. The hostid is generated partly based on the network setup. During the installation in the archiso the network configuration could be different generating a different hostid than the one contained in the new installation. Once the zfs filesystem is exported and then re-imported in the new installation, the hostid is reset. See [http://osdir.com/ml/zfs-discuss/2011-06/msg00227.html Re: Howto zpool import/export automatically? - msg#00227]{{Dead link|2020|04|03|status=404}}.<br />
<br />
If ZFS complains about "pool may be in use" after every reboot, properly export pool as described above, and then [[regenerate the initramfs]] in normally booted system.<br />
<br />
==== Incorrect hostid ====<br />
<br />
Double check that the pool is properly exported. Exporting the zpool clears the hostid marking the ownership. So during the first boot the zpool should mount correctly. If it does not there is some other problem.<br />
<br />
Reboot again, if the zfs pool refuses to mount it means the hostid is not yet correctly set in the early boot phase and it confuses zfs. Manually tell zfs the correct number, once the hostid is coherent across the reboots the zpool will mount correctly.<br />
<br />
Boot using zfs_force and write down the hostid. This one is just an example.<br />
<br />
{{hc|$ hostid|<br />
0a0af0f8<br />
}}<br />
<br />
This number have to be added to the [[kernel parameters]] as {{ic|1=spl.spl_hostid=0x0a0af0f8}}. Another solution is writing the hostid inside the initram image, see the [[Installing Arch Linux on ZFS#After the first boot|installation guide]]{{Broken section link}} explanation about this.<br />
<br />
Users can always ignore the check adding {{ic|1=zfs_force=1}} in the [[kernel parameters]], but it is not advisable as a permanent solution.<br />
<br />
=== Devices have different sector alignment ===<br />
<br />
Once a drive has become faulted it should be replaced A.S.A.P. with an identical drive.<br />
<br />
# zpool replace bigdata ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-1CH166_W1F478BD -f<br />
<br />
but in this instance, the following error is produced:<br />
<br />
cannot replace ata-ST3000DM001-9YN166_S1F0KDGY with ata-ST3000DM001-1CH166_W1F478BD: devices have different sector alignment<br />
<br />
ZFS uses the ashift option to adjust for physical block size. When replacing the faulted disk, ZFS is attempting to use {{ic|<nowiki>ashift=12</nowiki>}}, but the faulted disk is using a different ashift (probably {{ic|<nowiki>ashift=9</nowiki>}}) and this causes the resulting error. <br />
<br />
For Advanced Format Disks with 4KB blocksize, an ashift of 12 is recommended for best performance. See [https://github.com/zfsonlinux/zfs/wiki/faq#performance-considerations 1.10 What’s going on with performance?] and [http://wiki.illumos.org/display/illumos/ZFS+and+Advanced+Format+disks ZFS and Advanced Format disks].<br />
<br />
Use zdb to find the ashift of the zpool: {{ic|zdb | grep ashift}}, then use the {{ic|-o}} argument to set the ashift of the replacement drive:<br />
<br />
# zpool replace bigdata ata-ST3000DM001-9YN166_S1F0KDGY ata-ST3000DM001-1CH166_W1F478BD -o ashift=9 -f<br />
<br />
Check the zpool status for confirmation:<br />
<br />
{{hc|# zpool status -v|<br />
pool: bigdata<br />
state: DEGRADED<br />
status: One or more devices is currently being resilvered. The pool will<br />
continue to function, possibly in a degraded state.<br />
action: Wait for the resilver to complete.<br />
scan: resilver in progress since Mon Jun 16 11:16:28 2014<br />
10.3G scanned out of 5.90T at 81.7M/s, 20h59m to go<br />
2.57G resilvered, 0.17% done<br />
config:<br />
<br />
NAME STATE READ WRITE CKSUM<br />
bigdata DEGRADED 0 0 0<br />
raidz1-0 DEGRADED 0 0 0<br />
replacing-0 OFFLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KDGY OFFLINE 0 0 0<br />
ata-ST3000DM001-1CH166_W1F478BD ONLINE 0 0 0 (resilvering)<br />
ata-ST3000DM001-9YN166_S1F0JKRR ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0KBP8 ONLINE 0 0 0<br />
ata-ST3000DM001-9YN166_S1F0JTM1 ONLINE 0 0 0<br />
<br />
errors: No known data errors<br />
}}<br />
<br />
=== Pool resilvering stuck/restarting/slow? ===<br />
<br />
According to the ZFSonLinux github it is a known issue since 2012 with ZFS-ZED which causes the resilvering process to constantly restart, sometimes get stuck and be generally slow for some hardware. The simplest mitigation is to stop zfs-zed.service until the resilver completes<br />
<br />
=== Fix slow boot caused by failed import of unavailable pools in the initramfs zpool.cache ===<br />
<br />
Your boot time can be significantly impacted if you update your intitramfs (eg when doing a kernel update) when you have additional but non-permanently attached pools imported because these pools will get added to your initramfs zpool.cache and ZFS will attempt to import these extra pools on every boot, regardless of whether you have exported it and removed it from your regular zpool.cache.<br />
<br />
If you notice ZFS trying to import unavailable pools at boot, first run:<br />
<br />
$ zdb -C<br />
<br />
To check your zpool.cache for pools you do not want imported at boot. If this command is showing (a) additional, currently unavailable pool(s), run:<br />
<br />
# zpool set cachefile=/etc/zfs/zpool.cache zroot<br />
<br />
To clear the zpool.cache of any pools other than the pool named zroot. Sometimes there is no need to refresh your zpool.cache, but instead all you need to do is [[regenerate the initramfs]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Embed the archzfs packages into an archiso ===<br />
<br />
Follow the [[Archiso]] steps for creating a fully functional Arch Linux live CD/DVD/USB image.<br />
<br />
Enable the [[Unofficial user repositories#archzfs|archzfs]] repository:<br />
<br />
{{hc|~/archlive/pacman.conf|<nowiki><br />
...<br />
[archzfs]<br />
Server = http://archzfs.com/$repo/x86_64<br />
SigLevel = Optional TrustAll<br />
</nowiki>}}<br />
<br />
Add the {{ic|archzfs-linux}} group to the list of packages to be installed (the {{ic|archzfs}} repository provides packages for the x86_64 architecture only).<br />
<br />
{{hc|~/archlive/packages.x86_64|<br />
...<br />
archzfs-linux<br />
}}<br />
<br />
Complete [[Archiso#Build_the_ISO|Build the ISO]] to finally build the iso.<br />
<br />
{{Note|If you later have problems running modprobe zfs, you should include the linux-headers in the packages.x86_64. }}<br />
<br />
=== Automatic snapshots ===<br />
<br />
==== ZFS Automatic Snapshot Service for Linux ====<br />
<br />
The {{AUR|zfs-auto-snapshot-git}} package from [[AUR]] provides a shell script to automate the management of snapshots, with each named by date and label (hourly, daily, etc), giving quick and convenient snapshotting of all ZFS datasets. The package also installs cron tasks for quarter-hourly, hourly, daily, weekly, and monthly snapshots. Optionally adjust the {{ic|--keep parameter}} from the defaults depending on how far back the snapshots are to go (the monthly script by default keeps data for up to a year).<br />
<br />
To prevent a dataset from being snapshotted at all, set {{ic|1=com.sun:auto-snapshot=false}} on it. Likewise, set more fine-grained control as well by label, if, for example, no monthlies are to be kept on a snapshot, for example, set {{ic|1=com.sun:auto-snapshot:monthly=false}}.<br />
<br />
{{Note|zfs-auto-snapshot-git will not create snapshots during [[#Scrubbing|scrubbing]]. It is possible to override this by [[Systemd#Editing provided units|editing provided systemd unit]] and removing `--skip-scrub` from `ExecStart` line. Consequences not known, someone please edit.}}<br />
<br />
Once the package has been installed, [[systemd/Timers|enable and start the selected timers]] ({{ic|<nowiki>zfs-auto-snapshot-{frequent,daily,weekly,monthly}.timer</nowiki>}}).<br />
<br />
==== ZFS Snapshot Manager ====<br />
<br />
The {{AUR|zfs-snap-manager}} package from [[AUR]] provides a python service that takes daily snapshots from a configurable set of ZFS datasets and cleans them out in a [[wikipedia:Backup rotation scheme#Grandfather-father-son|"Grandfather-father-son"]] scheme. It can be configured to e.g. keep 7 daily, 5 weekly, 3 monthly and 2 yearly snapshots. <br />
<br />
The package also supports configurable replication to other machines running ZFS by means of {{ic|zfs send}} and {{ic|zfs receive}}. If the destination machine runs this package as well, it could be configured to keep these replicated snapshots for a longer time. This allows a setup where a source machine has only a few daily snapshots locally stored, while on a remote storage server a much longer retention is available.<br />
<br />
==== zrepl ====<br />
<br />
The {{AUR|zrepl}} package from the [[AUR]] provides a ZFS automatic replication service, which could also be used as a snapshotting service much like [[snapper]].<br />
<br />
For details on how to configure the zrepl daemon, see the zrepl [https://zrepl.github.io/ documentation]. The configuration file should be located at {{ic|/etc/zrepl/zrepl.yml}}. Then, run {{ic|zrepl configcheck}} to make sure that the syntax of the config file is correct. Finally, enable {{ic|zrepl.service}}.<br />
<br />
=== Creating a share ===<br />
<br />
ZFS has support for creating shares by [[NFS]] or [[SMB]].<br />
<br />
==== NFS ====<br />
<br />
Make sure [[NFS]] has been installed/configured, note there is no need to edit the {{ic|/etc/exports}} file. For sharing over NFS the services {{ic|nfs-server.service}} and {{ic|zfs-share.service}} should be [[start|started]].<br />
<br />
To make a pool available on the network:<br />
<br />
# zfs set sharenfs=on <nameofzpool><br />
<br />
To make a dataset available on the network:<br />
<br />
# zfs set sharenfs=on <nameofzpool>/<nameofdataset><br />
<br />
To enable read/write access for a specific ip-range(s):<br />
<br />
# zfs set sharenfs="rw=@192.168.1.100/24,rw=@10.0.0.0/24" <nameofzpool>/<nameofdataset><br />
<br />
To check if the dataset is exported successful:<br />
<br />
{{hc|# showmount -e `hostname`|<br />
Export list for hostname:<br />
/path/of/dataset 192.168.1.100/24<br />
}}<br />
<br />
To view the current loaded exports state in more detail, use:<br />
<br />
{{hc|# exportfs -v|2=<br />
/path/of/dataset<br />
192.168.1.100/24(sync,wdelay,hide,no_subtree_check,mountpoint,sec=sys,rw,secure,no_root_squash,no_all_squash)<br />
}}<br />
<br />
==== SMB ====<br />
<br />
When sharing smb shares configuring usershares in your smb.conf will allow ZFS to setup and create the shares.<br />
<br />
{{bc|1=<br />
# [global]<br />
# usershare path = /var/lib/samba/usershares<br />
# usershare max shares = 100<br />
# usershare allow guests = yes<br />
# usershare owner only = no<br />
}}<br />
<br />
Create and set permissions on the user directory as root<br />
<br />
# mkdir /var/lib/samba/usershares<br />
# chmod +t /var/lib/samba/usershares<br />
<br />
To make a pool available on the network:<br />
<br />
# zfs set sharesmb=on <nameofzpool><br />
<br />
To make a dataset available on the network:<br />
<br />
# zfs set sharesmb=on <nameofzpool>/<nameofdataset><br />
<br />
To check if the dataset is exported successfully:<br />
<br />
{{hc|# smbclient -L localhost -U%|<br />
Sharename Type Comment<br />
--------- ---- -------<br />
IPC$ IPC IPC Service (SMB Server Name)<br />
<nameofzpool>_<nameofdataset> Disk Comment: path/of/dataset<br />
SMB1 disabled -- no workgroup available<br />
}}<br />
<br />
=== Encryption in ZFS using dm-crypt ===<br />
<br />
The stable release version of ZFS on Linux used to not support encryption directly (now it's available, see [[#Native encryption]]), but zpools can be created on dm-crypt block devices. Since the zpool is created on the plain-text abstraction, it is possible to have the data encrypted while having all the advantages of ZFS like deduplication, compression, and data robustness.<br />
<br />
dm-crypt, possibly via LUKS, creates devices in {{ic|/dev/mapper}} and their name is fixed. So you just need to change {{ic|zpool create}} commands to point to that names. The idea is configuring the system to create the {{ic|/dev/mapper}} block devices and import the zpools from there. Since zpools can be created in multiple devices (raid, mirroring, striping, ...), it is important all the devices are encrypted otherwise the protection might be partially lost.<br />
<br />
For example, an encrypted zpool can be created using plain dm-crypt (without LUKS) with:<br />
<br />
# cryptsetup --hash=sha512 --cipher=twofish-xts-plain64 --offset=0 \<br />
--key-file=/dev/sdZ --key-size=512 open --type=plain /dev/sdX enc<br />
# zpool create zroot /dev/mapper/enc<br />
<br />
In the case of a root filesystem pool, the {{ic|mkinitcpio.conf}} HOOKS line will enable the keyboard for the password, create the devices, and load the pools. It will contain something like:<br />
<br />
HOOKS="... keyboard encrypt zfs ..."<br />
<br />
Since the {{ic|/dev/mapper/enc}} name is fixed no import errors will occur.<br />
<br />
Creating encrypted zpools works fine. But if you need encrypted directories, for example to protect your users' homes, ZFS loses some functionality.<br />
<br />
ZFS will see the encrypted data, not the plain-text abstraction, so compression and deduplication will not work. The reason is that encrypted data has always high entropy making compression ineffective and even from the same input you get different output (thanks to salting) making deduplication impossible. To reduce the unnecessary overhead it is possible to create a sub-filesystem for each encrypted directory and use [[eCryptfs]] on it.<br />
<br />
For example to have an encrypted home: (the two passwords, encryption and login, must be the same)<br />
<br />
# zfs create -o compression=off -o dedup=off -o mountpoint=/home/<username> <zpool>/<username><br />
# useradd -m <username><br />
# passwd <username><br />
# ecryptfs-migrate-home -u <username><br />
<log in user and complete the procedure with ecryptfs-unwrap-passphrase><br />
<br />
=== Emergency chroot repair with archzfs ===<br />
<br />
To get into the ZFS filesystem from live system for maintenance, there are two options:<br />
<br />
# Build custom archiso with ZFS as described in [[#Embed the archzfs packages into an archiso]].<br />
# Boot the latest official archiso and bring up the network. Then enable [[Unofficial_user_repositories#archzfs|archzfs]] repository inside the live system as usual, sync the pacman package database and install the ''archzfs-archiso-linux'' package.<br />
<br />
To start the recovery, load the ZFS kernel modules:<br />
<br />
# modprobe zfs<br />
<br />
Import the pool:<br />
<br />
# zpool import -a -R /mnt<br />
<br />
Mount the boot partitions (if any):<br />
<br />
# mount /dev/sda2 /mnt/boot<br />
# mount /dev/sda1 /mnt/boot/efi<br />
<br />
Chroot into the ZFS filesystem:<br />
<br />
# arch-chroot /mnt /bin/bash<br />
<br />
Check the kernel version:<br />
<br />
# pacman -Qi linux<br />
# uname -r<br />
<br />
uname will show the kernel version of the archiso. If they are different, run depmod (in the chroot) with the correct kernel version of the chroot installation:<br />
<br />
# depmod -a 3.6.9-1-ARCH (version gathered from pacman -Qi linux but using the matching kernel modules directory name under the chroot's /lib/modules)<br />
<br />
This will load the correct kernel modules for the kernel version installed in the chroot installation.<br />
<br />
[[Regenerate the initramfs]]. There should be no errors.<br />
<br />
=== Bind mount ===<br />
<br />
Here a bind mount from /mnt/zfspool to /srv/nfs4/music is created. The configuration ensures that the zfs pool is ready before the bind mount is created.<br />
<br />
==== fstab ====<br />
<br />
See [https://www.freedesktop.org/software/systemd/man/systemd.mount.html systemd.mount] for more information on how systemd converts fstab into mount unit files with [https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html systemd-fstab-generator].<br />
<br />
{{hc|/etc/fstab|<nowiki><br />
/mnt/zfspool /srv/nfs4/music none bind,defaults,nofail,x-systemd.requires=zfs-mount.service 0 0<br />
</nowiki>}}<br />
<br />
=== Monitoring / Mailing on Events ===<br />
<br />
See [https://ramsdenj.com/2016/08/29/arch-linux-on-zfs-part-3-followup.html ZED: The ZFS Event Daemon] for more information.<br />
<br />
An email forwarder, such as [[S-nail]] (installed as part of {{Pkg|base}}), is required to accomplish this. Test it to be sure it is working correctly.<br />
<br />
Uncomment the following in the configuration file:<br />
<br />
{{hc|/etc/zfs/zed.d/zed.rc|<nowiki><br />
ZED_EMAIL_ADDR="root"<br />
ZED_EMAIL_PROG="mailx"<br />
ZED_NOTIFY_VERBOSE=0<br />
ZED_EMAIL_OPTS="-s '@SUBJECT@' @ADDRESS@"<br />
</nowiki>}}<br />
<br />
Update 'root' in {{ic|1=ZED_EMAIL_ADDR="root"}} to the email address you want to receive notifications at.<br />
<br />
If you are keeping your mailrc in your home directory, you can tell mail to get it from there by setting {{ic|MAILRC}}:<br />
<br />
{{hc|/etc/zfs/zed.d/zed.rc|2=<br />
export MAILRC=/home/<user>/.mailrc<br />
}}<br />
<br />
This works because ZED sources this file, so {{ic|mailx}} sees this environment variable.<br />
<br />
If you want to receive an email no matter the state of your pool, you will want to set {{ic|1=ZED_NOTIFY_VERBOSE=1}}. You will need to do this temporary to test.<br />
<br />
[[Start]] and [[enable]] {{ic|zfs-zed.service}}.<br />
<br />
With {{ic|1=ZED_NOTIFY_VERBOSE=1}}, you can test by running a scrub as root: {{ic|1=zpool scrub <pool-name>}}.<br />
<br />
=== Wrap shell commands in pre & post snapshots ===<br />
<br />
Since it is so cheap to make a snapshot, we can use this as a measure of security for sensitive commands such as system and package upgrades. If we make a snapshot before, and one after, we can later diff these snapshots to find out what changed on the filesystem after the command executed. Furthermore we can also rollback in case the outcome was not desired.<br />
<br />
E.g.:<br />
<br />
# zfs snapshot -r zroot@pre<br />
# pacman -Syu<br />
# zfs snapshot -r zroot@post<br />
# zfs diff zroot@pre zroot@post <br />
# zfs rollback zroot@pre<br />
<br />
A utility that automates the creation of pre and post snapshots around a shell command is [https://gist.github.com/erikw/eeec35be33e847c211acd886ffb145d5 znp].<br />
<br />
E.g.:<br />
<br />
# znp pacman -Syu<br />
# znp find / -name "something*" -delete<br />
<br />
and you would get snapshots created before and after the supplied command, and also output of the commands logged to file for future reference so we know what command created the diff seen in a pair of pre/post snapshots.<br />
<br />
=== Remote unlocking of ZFS encrypted root ===<br />
<br />
As of [https://github.com/archzfs/archzfs/pull/261 PR #261], {{ic|archzfs}} supports SSH unlocking of natively-encrypted ZFS datasets. This section describes how to use this feature, and is largely based on [[dm-crypt/Specialties#Remote unlocking (hooks: netconf, dropbear, tinyssh, ppp)]].<br />
<br />
#Install {{Pkg|mkinitcpio-netconf}} to provide hooks for setting up early user space networking.<br />
#Choose an SSH server to use in early user space. The options are {{Pkg|mkinitcpio-tinyssh}} or {{Pkg|mkinitcpio-dropbear}}, and are mutually exclusive.<br />
##If using {{Pkg|mkinitcpio-tinyssh}}, it is also recommended to install {{Pkg|tinyssh-convert}} or {{AUR|tinyssh-convert-git}}. This tool converts an existing OpenSSH hostkey to the TinySSH key format, preserving the key fingerprint and avoiding connection warnings. The TinySSH and Dropbear mkinitcpio install scripts will automatically convert existing hostkeys when generating a new initcpio image.<br />
#Decide whether to use an existing OpenSSH key or generate a new one (recommended) for the host that will be connecting to and unlocking the encrypted ZFS machine. Copy the public key into {{ic|/etc/tinyssh/root_key}} or {{ic|/etc/dropbear/root_key}}. When generating the initcpio image, this file will be added to {{ic|authorized_keys}} for the root user and is only valid in the initrd environment.<br />
#Add the {{ic|1=ip=}} [[kernel parameter]] to your boot loader configuration. The {{ic|ip}} string is [https://www.kernel.org/doc/html/latest/admin-guide/nfs/nfsroot.html highly configurable]. A simple DHCP example is shown below.{{bc|1=ip=:::::eth0:dhcp}}<br />
#Edit {{ic|/etc/mkinitcpio.conf}} to include the {{ic|netconf}}, {{ic|dropbear}} or {{ic|tinyssh}}, and {{ic|zfsencryptssh}} hooks before the {{ic|zfs}} hook:{{bc|1=HOOKS=(... netconf <tinyssh>{{!}}<dropbear> zfsencryptssh zfs ...)}}<br />
#[[Regenerate the initramfs]].<br />
#Reboot and try it out!<br />
<br />
====Changing the SSH server port====<br />
<br />
By default, {{Pkg|mkinitcpio-tinyssh}} and {{Pkg|mkinitcpio-dropbear}} listen on port {{ic|22}}. You may wish to change this.<br />
<br />
For '''TinySSH''', copy {{ic|/usr/lib/initcpio/hooks/tinyssh}} to {{ic|/etc/initcpio/hooks/tinyssh}}, and find/modify the following line in the {{ic|run_hook()}} function:<br />
<br />
{{hc|/etc/initcpio/hooks/tinyssh|<br />
/usr/bin/tcpserver -HRDl0 0.0.0.0 <new_port> /usr/sbin/tinysshd -v /etc/tinyssh/sshkeydir &<br />
}}<br />
<br />
For '''Dropbear''', copy {{ic|/usr/lib/initcpio/hooks/dropbear}} to {{ic|/etc/initcpio/hooks/dropbear}}, and find/modify the following line in the {{ic|run_hook()}} function:<br />
<br />
{{hc|/etc/initcpio/hooks/tinyssh|<br />
/usr/sbin/dropbear -E -s -j -k -p <new_port><br />
}}<br />
<br />
[[Regenerate the initramfs]].<br />
<br />
==== Unlocking from a Windows machine using PuTTY/Plink ====<br />
<br />
First, we need to use {{ic|puttygen.exe}} to import and convert the OpenSSH key generated earlier into PuTTY's ''.ppk'' private key format. Let us call it {{ic|zfs_unlock.ppk}} for this example.<br />
<br />
The mkinitcpio-netconf process above does not setup a shell (nor do we need need one). However, because there is no shell, PuTTY will immediately close after a successful connection. This can be disabled in the PuTTY SSH configuration (''Connection -> SSH -> [X] Do not start a shell or command at all''), but it still does not allow us to see stdout or enter the encryption passphrase. Instead, we use {{ic|plink.exe}} with the following parameters:<br />
<br />
plink.exe -ssh -l root -i c:\path\to\zfs_unlock.ppk <hostname><br />
<br />
The plink command can be put into a batch script for ease of use.<br />
<br />
== See also ==<br />
<br />
* [https://pthree.org/2012/12/04/zfs-administration-part-i-vdevs/ Aaron Toponce's 17-part blog on ZFS]<br />
* [http://zfsonlinux.org/ ZFS on Linux]<br />
* [https://github.com/zfsonlinux/zfs/wiki/faq ZFS on Linux FAQ]<br />
* [https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/zfs.html FreeBSD Handbook - The Z File System]<br />
* [https://docs.oracle.com/cd/E19253-01/819-5461/index.html Oracle Solaris ZFS Administration Guide]<br />
* [https://web.archive.org/web/20161028084224/http://www.solarisinternals.com/wiki/index.php/ZFS_Best_Practices_Guide ZFS Best Practices Guide]<br />
* [https://docs.oracle.com/cd/E23823_01/html/819-5461/gavwg.html ZFS Troubleshooting Guide]<br />
* [http://royal.pingdom.com/2013/06/04/zfs-backup/ How Pingdom uses ZFS to back up 5TB of MySQL data every day]<br />
* [https://www.linuxquestions.org/questions/linux-from-scratch-13/%5Bhow-to%5D-add-zfs-to-the-linux-kernel-4175514510/ Tutorial on adding the modules to a custom kernel]<br />
* [https://github.com/danboid/creating-ZFS-disks-under-Linux How to create cross platform ZFS disks under Linux]<br />
* [https://blog.heckel.xyz/2017/01/08/zfs-encryption-openzfs-zfs-on-linux/ How-To: Using ZFS Encryption at Rest in OpenZFS (ZFS on Linux, ZFS on FreeBSD, …)]</div>Ondrianhttps://wiki.archlinux.org/index.php?title=Dual_boot_with_Windows&diff=573305Dual boot with Windows2019-05-15T22:23:04Z<p>Ondrian: /* UEFI systems */ Link the possibility to use os-prober to auto-detect Windows.</p>
<hr />
<div>[[Category:Boot process]]<br />
[[Category:Installation process]]<br />
[[es:Dual boot with Windows]]<br />
[[ja:Windows と Arch のデュアルブート]]<br />
[[ru:Dual boot with Windows]]<br />
[[sk:Dual boot with Windows]]<br />
[[zh-hans:Dual boot with Windows]]<br />
{{Related articles start}}<br />
{{Related|Dual boot with Windows/SafeBoot}}<br />
{{Related articles end}}<br />
<br />
This is an article detailing different methods of Arch/Windows coexistence.<br />
<br />
== Important information ==<br />
<br />
=== Windows UEFI vs BIOS limitations ===<br />
<br />
Microsoft imposes limitations on which firmware boot mode and partitioning style can be supported based on the version of Windows used:<br />
<br />
* '''Windows XP''' both '''x86 32-bit''' and '''x86_64''' (also called x64) (RTM and all Service Packs) versions do not support booting in UEFI mode (IA32 or x86_64) from any disk (MBR or GPT) OR in BIOS mode from GPT disk. They support only BIOS boot and only from MBR disk.<br />
* '''Windows Vista''' or '''7''' '''x86 32-bit''' (RTM and all Service Packs) versions support booting in BIOS mode from MBR disks only, not from GPT disks. They do not support x86_64 UEFI or IA32 (x86 32-bit) UEFI boot. They support only BIOS boot and only from MBR disk.<br />
* '''Windows Vista RTM x86_64''' (only RTM) version support booting in BIOS mode from MBR disks only, not from GPT disks. It does not support x86_64 UEFI or IA32 (x86 32-bit) UEFI boot. It supports only BIOS boot and only from MBR disk.<br />
* '''Windows Vista''' (SP1 and above, not RTM) and '''Windows 7''' '''x86_64''' versions support booting in x86_64 UEFI mode from GPT disk only, OR in BIOS mode from MBR disk only. They do not support IA32 (x86 32-bit) UEFI boot from GPT/MBR disk, x86_64 UEFI boot from MBR disk, or BIOS boot from GPT disk.<br />
* '''Windows 8/8.1 x86 32-bit''' support booting in IA32 UEFI mode from GPT disk only, OR in BIOS mode from MBR disk only. They do not support x86_64 UEFI boot from GPT/MBR disk, x86_64 UEFI boot from MBR disk, or BIOS boot from GPT disk. On market, the only systems known to ship with IA32 (U)EFI are some old Intel Macs (pre-2010 models?) and Intel Atom System-on-Chip (Clover trail and Bay Trail) Windows Tablets. in which it boots ONLY in IA32 UEFI mode and ONLY from GPT disk.<br />
* '''Windows 8/8.1''' '''x86_64''' versions support booting in x86_64 UEFI mode from GPT disk only, OR in BIOS mode from MBR disk only. They do not support IA32 UEFI boot, x86_64 UEFI boot from MBR disk, or BIOS boot from GPT disk.<br />
<br />
In case of pre-installed Systems:<br />
<br />
* All systems pre-installed with Windows XP, Vista or 7 32-bit, irrespective of Service Pack level, bitness, edition (SKU) or presence of UEFI support in firmware, boot in BIOS/MBR mode by default.<br />
* MOST of the systems pre-installed with Windows 7 x86_64, irrespective of Service Pack level, bitness or edition (SKU), boot in BIOS/MBR mode by default. Very few recent systems pre-installed with Windows 7 are known to boot in x86_64 UEFI/GPT mode by default.<br />
* ALL systems pre-installed with Windows 8/8.1 boot in UEFI/GPT mode. The firmware bitness matches the bitness of Windows, ie. x86_64 Windows 8/8.1 boot in x86_64 UEFI mode and 32-bit Windows 8/8.1 boot in IA32 UEFI mode.<br />
<br />
The best way to detect the boot mode of Windows is to do the following[http://www.eightforums.com/tutorials/29504-bios-mode-see-if-windows-boot-uefi-legacy-mode.html]:<br />
<br />
* Boot into Windows<br />
* Press {{ic|Win+R}} keys to start the Run dialog<br />
* In the Run dialog type {{ic|msinfo32.exe}} and press Enter<br />
* In the '''System Information''' windows, select ''System Summary'' on the left and check the value of '''BIOS mode''' item on the right<br />
* If the value is {{ic|UEFI}}, Windows boots in UEFI/GPT mode. If the value is {{ic|Legacy}}, Windows boots in BIOS/MBR mode.<br />
<br />
In general, Windows forces type of partitioning depending on the firmware mode used, i.e. if Windows is booted in UEFI mode, it can be installed only to a GPT disk. If the Windows is booted in Legacy BIOS mode, it can be installed only to a MBR disk. This is a limitation enforced by Windows installer, and as of April 2014 there is no officially (Microsoft) supported way of installing Windows in UEFI/MBR or BIOS/GPT configuration. Thus Windows only supports either UEFI/GPT boot or BIOS/MBR configuration.<br />
<br />
{{Tip|Windows 10 version 1703 and newer supports converting from BIOS/MBR to UEFI/GPT using [https://docs.microsoft.com/en-us/windows/deployment/mbr-to-gpt MBR2GPT.EXE].}}<br />
<br />
Such a limitation is not enforced by the Linux kernel, but can depend on which [[boot loader]] is used and/or how the boot loader is configured. The Windows limitation should be considered if the user wishes to boot Windows and Linux from the same disk, since installation procedure of boot loader depends on the firmware type and disk [[partitioning]] configuration. In case where Windows and Linux dual boot from the same disk, it is advisable to follow the method used by Windows, ie. either go for UEFI/GPT boot or BIOS/MBR boot. See http://support.microsoft.com/kb/2581408 for more information.<br />
<br />
=== Install media limitations ===<br />
<br />
Intel Atom System-on-Chip Tablets (Clover trail and Bay Trail) provide only IA32 UEFI firmware without Legacy BIOS (CSM) support (unlike most of the x86_64 UEFI systems), due to Microsoft Connected Standby Guidelines for OEMs. Due to lack of Legacy BIOS support in these systems, and the lack of 32-bit UEFI boot in Arch Official Install ISO ({{Bug|53182}}), the official install media cannot boot on these systems. See [[Unified Extensible Firmware Interface#UEFI firmware bitness]] for more information and available workarounds.<br />
<br />
=== Bootloader UEFI vs BIOS limitations ===<br />
<br />
Most of the linux bootloaders installed for one firmware type cannot launch or chainload bootloaders of the other firmware type. That is, if Arch is installed in UEFI/GPT or UEFI/MBR mode in one disk and Windows is installed in BIOS/MBR mode in another disk, the UEFI bootloader used by Arch cannot chainload the BIOS installed Windows in the other disk. Similarly if Arch is installed in BIOS/MBR or BIOS/GPT mode in one disk and Windows is installed in UEFI/GPT in another disk , the BIOS bootloader used by Arch cannot chainload UEFI installed Windows in the other disk. <br />
<br />
The only exceptions to this are [[GRUB]] in Apple Macs in which GRUB in UEFI mode can boot BIOS installed OS via {{ic|appleloader}} command (does not work in non-Apple systems), and [[rEFInd]] which technically supports booting legacy BIOS OS from UEFI systems, but [http://rodsbooks.com/refind/using.html#legacy does not always work in non-Apple UEFI systems] as per its author Rod Smith. <br />
<br />
However if Arch is installed in BIOS/GPT in one disk and Windows is installed in BIOS/MBR mode in another disk, then the BIOS boot loader used by Arch CAN boot the Windows in the other disk, if the boot loader itself has the ability to chainload from another disk. <br />
<br />
{{Note|If Arch and Windows are dual-booting from same disk, then Arch should follow the same firmware boot mode and partitioning combination used by the installed Windows in the disk.}}<br />
<br />
=== UEFI Secure Boot ===<br />
<br />
All pre-installed Windows 8/8.1 systems by default boot in UEFI/GPT mode and have UEFI Secure Boot enabled by default. This is mandated by Microsoft for all OEM pre-installed systems.<br />
<br />
Arch Linux install media does not support Secure Boot. See [[Secure Boot#Booting archiso]]{{Broken section link}}. <br />
<br />
It is advisable to disable UEFI Secure Boot in the firmware setup manually before attempting to boot Arch Linux. Windows 8/8.1 SHOULD continue to boot fine even if Secure boot is disabled. The only issue with regards to disabling UEFI Secure Boot support is that it requires physical access to the system to disable secure boot option in the firmware setup, as Microsoft has explicitly forbidden presence of any method to remotely or programmatically (from within OS) disable secure boot in all Windows 8/8.1 pre-installed systems<br />
<br />
=== Fast Start-Up ===<br />
<br />
Fast Start-Up is a feature in Windows 8 and above that hibernates the computer rather than actually shutting it down to speed up boot times. Your system can lose data if Windows hibernates and you dual boot into another OS and make changes to files. Even if you do not intend to share filesystems, the EFI System Partition is likely to be damaged on an EFI system. Therefore, you should disable Fast Startup, as described [http://www.eightforums.com/tutorials/6320-fast-startup-turn-off-windows-8-a.html here for Windows 8] and [http://www.tenforums.com/tutorials/4189-fast-startup-turn-off-windows-10-a.html here for Windows 10], before you install Linux on any computer that uses Windows 8 or above.<br />
<br />
{{Pkg|ntfs-3g}} added a [http://sourceforge.net/p/ntfs-3g/ntfs-3g/ci/559270a8f67c77a7ce51246c23d2b2837bcff0c9/ safe-guard] to prevent read-write mounting of hibernated disks, but the NTFS driver within the Linux kernel has no such safeguard.<br />
<br />
=== Windows filenames limitations ===<br />
<br />
Windows is limited to filepaths being shorter than [http://blogs.msdn.com/b/bclteam/archive/2007/02/13/long-paths-in-net-part-1-of-3-kim-hamilton.aspx 260 characters].<br />
<br />
Windows also puts [http://msdn.microsoft.com/en-us/library/aa365247(VS.85).aspx#naming_conventions certain characters off limits] in filenames for reasons that run all the way back to DOS:<br />
<br />
* {{ic|<}} (less than)<br />
* {{ic|>}} (greater than)<br />
* {{ic|:}} (colon)<br />
* {{ic|"}} (double quote)<br />
* {{ic|/}} (forward slash)<br />
* {{ic|\}} (backslash)<br />
* {{ic|{{!}}}} (vertical bar or pipe)<br />
* {{ic|?}} (question mark)<br />
* {{ic|*}} (asterisk)<br />
<br />
These are limitations of Windows and not NTFS: any other OS using the NTFS partition will be fine. Windows will fail to detect these files and running {{ic|chkdsk}} will most likely cause them to be deleted. This can lead to potential data-loss.<br />
<br />
[[NTFS-3G]] applies Windows restrictions to new file names through the [http://www.tuxera.com/community/ntfs-3g-manual/#4 windows_names] option (see [[fstab]]).<br />
<br />
== Installation ==<br />
<br />
The recommended way to setup a Linux/Windows dual booting system is to first install Windows, only using part of the disk for its partitions. When you have finished the Windows setup, boot into the Linux install environment where you can create and resize partitions for Linux while leaving the existing Windows partitions untouched. The Windows installation will create the [[EFI system partition]] which can be used by your Linux [[boot loader]].<br />
<br />
=== BIOS systems ===<br />
<br />
==== Using a Linux boot loader ====<br />
<br />
You may use any multi-boot supporting BIOS [[boot loader]].<br />
<br />
==== Using Windows boot loader ====<br />
<br />
With this setup the Windows bootloader loads GRUB which then boots Arch. <br />
<br />
===== Windows Vista/7/8/8.1 boot loader =====<br />
<br />
{{Style|Contains personal comments.}}<br />
<br />
The following section contains excerpts from http://www.iceflatline.com/2009/09/how-to-dual-boot-windows-7-and-linux-using-bcdedit/.<br />
<br />
{{Accuracy|Using ext3 formatted /boot partition, windows bootloader works just fine}}<br />
<br />
In order to have the Windows boot loader see the Linux partition, one of the Linux partitions created needs to be FAT32 (in this case, {{ic|/dev/sda3}}). The remainder of the setup is similar to a typical installation. Some documents state that the partition being loaded by the Windows boot loader must be a primary partition but I have used this without problem on an extended partition.<br />
<br />
* When installing the GRUB boot loader, install it on your {{ic|/boot}} partition rather than the MBR. {{Note|For instance, my {{ic|/boot}} partition is {{ic|/dev/sda5}}. So I installed GRUB at {{ic|/dev/sda5}} instead of {{ic|/dev/sda}}. For help on doing this, see [[GRUB/Tips and tricks#Install to partition or partitionless disk]].}}<br />
<br />
* Under Linux make a copy of the boot info by typing the following at the command shell:<br />
<br />
my_windows_part=/dev/sda3<br />
my_boot_part=/dev/sda5<br />
mkdir /media/win<br />
mount $my_windows_part /media/win<br />
dd if=$my_boot_part of=/media/win/linux.bin bs=512 count=1<br />
<br />
* Boot to Windows and open up and you should be able to see the linux.bin file at {{ic|C:\}}. Now run '''cmd''' with administrator privileges (navigate to ''Start > All Programs > Accessories'', right-click on ''Command Prompt'' and select ''Run as administrator''):<br />
<br />
bcdedit /create /d "Linux" /application BOOTSECTOR<br />
<br />
* BCDEdit will return a [[wikipedia:Universally_unique_identifier|UUID]] for this entry that I will refer to as {ID} in the remaining steps. You will need to replace {ID} by the actual returned identifier. An example of {ID} is {d7294d4e-9837-11de-99ac-f3f3a79e3e93}. <br />
<br />
bcdedit /set {ID} device partition=c:<br />
bcdedit /set {ID} path \linux.bin<br />
bcdedit /displayorder {ID} /addlast<br />
bcdedit /timeout 30<br />
<br />
Reboot and enjoy. In my case I'm using the Windows boot loader so that I can map my Dell Precision M4500's second power button to boot Linux instead of Windows.<br />
<br />
=== UEFI systems ===<br />
<br />
If you already have Windows installed, it will already have created some partitions on a [[GPT]]-formatted disk:<br />
<br />
* a [[Wikipedia:Windows Recovery Environment|Windows Recovery Environment]] partition, generally of size 499 MiB, containing the files required to boot Windows (i.e. the equivalent of Linux's {{ic|/boot}}),<br />
* an [[EFI system partition]] with a [[FAT32]] filesystem,<br />
* a [[Wikipedia:Microsoft Reserved Partition|Microsoft Reserved Partition]], generally of size 128 MiB,<br />
* a Microsoft basic data partition with a NTFS filesystem, which corresponds to {{ic|C:}},<br />
* potentially system recovery and backup partitions and/or secondary data partitions (corresponding often to {{ic|D:}} and above).<br />
<br />
Using the Disk Management utility in Windows, check how the partitions are labelled and which type gets reported. This will help you understand which partitions are essential to Windows, and which others you might repurpose.<br />
<br />
{{Warning|The first 4 partitions in the above list are essential, do not delete them.}}<br />
<br />
You can then proceed with [[partitioning]], depending on your needs. Mind that there is no need to create an additional EFI system partition, since it already exists. Simply [[EFI system partition#Mount the partition|mount the existing partition]].<br />
<br />
The boot loader needs to support chainloading other EFI applications to do dual boot Windows / Linux.<br />
<br />
{{Tip|[[rEFInd]] and [[systemd-boot]] will autodetect ''Windows Boot Manager'' ({{ic|\EFI\Microsoft\Boot\bootmgfw.efi}}) and show it in their boot menu automatically. For [[GRUB]] follow either [[GRUB#Windows installed in UEFI/GPT mode]] to add boot menu entry manually or [[GRUB#Detecting_other_operating_systems]] for a generated grub config.}}<br />
<br />
Computers that come with newer versions of Windows often have [[Secure Boot]] enabled. You will need to take extra steps to either disable Secure Boot or to make your installation media compatible with secure boot (see above and in the linked page).<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Couldn't create a new partition or locate an existing one ====<br />
<br />
See [[#Windows UEFI vs BIOS limitations]].<br />
<br />
==== Cannot boot Linux after installing Windows ====<br />
<br />
See [[Unified Extensible Firmware Interface#Windows changes boot order]].<br />
<br />
==== Restoring a Windows boot record ====<br />
<br />
By convention (and for ease of installation), Windows is usually installed on the first partition and installs its partition table and reference to its bootloader to the first sector of that partition. If you accidentally install a bootloader like GRUB to the Windows partition or damage the boot record in some other way, you will need to use a utility to repair it. Microsoft includes a boot sector fix utility {{Ic|FIXBOOT}} and an MBR fix utility called {{Ic|FIXMBR}} on their recovery discs, or sometimes on their install discs. Using this method, you can fix the reference on the boot sector of the first partition to the bootloader file and fix the reference on the MBR to the first partition, respectively. After doing this you will have to [[GRUB#Installation|reinstall GRUB]] to the MBR as was originally intended (that is, the GRUB bootloader can be assigned to chainload the Windows bootloader).<br />
<br />
If you wish to revert back to using Windows, you can use the {{Ic|FIXBOOT}} command which chains from the MBR to the boot sector of the first partition to restore normal, automatic loading of the Windows operating system.<br />
<br />
Of note, there is a Linux utility called {{Ic|ms-sys}} (package {{AUR|ms-sys}} in AUR) that can install MBR's. However, this utility is only currently capable of writing new MBRs (all OS's and file systems supported) and boot sectors (a.k.a. boot record; equivalent to using {{Ic|FIXBOOT}}) for FAT file systems. Most LiveCDs do not have this utility by default, so it will need to be installed first, or you can look at a rescue CD that does have it, such as [http://partedmagic.com/ Parted Magic].<br />
<br />
First, write the partition info (table) again by:<br />
<br />
# ms-sys --partition /dev/sda1<br />
<br />
Next, write a Windows 2000/XP/2003 MBR:<br />
<br />
# ms-sys --mbr /dev/sda # Read options for different versions<br />
<br />
Then, write the new boot sector (boot record):<br />
<br />
# ms-sys -(1-6) # Read options to discover the correct FAT record type<br />
<br />
{{Ic|ms-sys}} can also write Windows 98, ME, Vista, and 7 MBRs as well, see {{Ic|ms-sys -h}}.<br />
<br />
== Time standard ==<br />
<br />
* Recommended: Set both Arch Linux and Windows to use UTC, following [[System time#UTC in Windows]]. Some versions of Windows revert the hardware clock back to ''localtime'' if they are set to synchronize the time online. This issue appear to be fixed in Windows 10.<br />
* Not recommended: Set Arch Linux to ''localtime'' and disable all [[System time#Time synchronization|time synchronization daemons]]. This will let Windows take care of hardware clock corrections and you will need to remember to boot into Windows at least two times a year (in Spring and Autumn) when [[Wikipedia:Daylight saving time|DST]] kicks in. So please do not ask on the forums why the clock is one hour behind or ahead if you usually go for days or weeks without booting into Windows.<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=140049 Booting Windows from a desktop shortcut]<br />
* [https://github.com/kaipee/grub-reboot2win One-time boot into Windows partition from desktop shortcut]<br />
* [https://github.com/ValdikSS/windows2usb Windows 7/8/8.1/10 ISO to Flash Drive burning utility for Linux (MBR/GPT, BIOS/UEFI, FAT32/NTFS)]</div>Ondrianhttps://wiki.archlinux.org/index.php?title=Mathematica&diff=557944Mathematica2018-12-01T12:54:43Z<p>Ondrian: /* Mathematica 11 */ fix link description</p>
<hr />
<div>[[Category:Numerical analysis]]<br />
[[it:Mathematica]]<br />
[[ja:Mathematica]]<br />
[[zh-hans:Mathematica]]<br />
{{Related articles start}}<br />
{{Related|Scientific Applications}}<br />
{{Related|Sage-mathematics}}<br />
{{Related|Matlab}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Wolfram Mathematica|Mathematica]] is a commercial program used in scientific, engineering and mathematical fields. Here we explain how to install it.<br />
<br />
== Installation ==<br />
<br />
Since Mathematica is a non-free application and upgrades may incur costs, this section lists instructions for different available versions. <br />
<br />
=== Mathematica 6 ===<br />
<br />
==== Mounting iso ====<br />
<br />
One way to mount the Mathematica {{ic|.iso}} is to create a {{ic|/media/iso}} mount directory and add the following line to the [[fstab]]:<br />
/''location/of/mathematica.iso'' /media/iso iso9660 exec,ro,user,noauto,loop=/dev/loop0 0 0<br />
Now you can mount it with:<br />
# mount /media/iso<br />
<br />
==== Running the Installer ====<br />
<br />
You can start the installer by navigating to:<br />
/Unix/Installer<br />
Run ''MathInstaller'' with:<br />
sh ./MathInstaller<br />
{{Note|If you do not place the "sh" in front, then you will get an error about a bad interpreter.}}<br />
<br />
==== Fonts ====<br />
<br />
Add the directories containing Type1 and BDF fonts to your FontPath.<br />
<br />
=== Mathematica 7 ===<br />
<br />
Mathematica 7 is much easier to install.<br />
<br />
tar xf Mathematica-7.0.1.tar.gz<br />
cd Unix/Installer<br />
./MathInstaller<br />
<br />
Follow instructions.<br />
<br />
For KDE users, the Mathematica icon may appear in the ''Lost & Found'' category. To solve this, execute the following as root:<br />
<br />
# ln -s /etc/xdg/menus/applications-merged /etc/xdg/menus/kde-applications-merged<br />
<br />
=== Mathematica 8 ===<br />
<br />
An issue with Mathematica 8 is a reproducible crash when performing WolframAlpha[] functions. By default, Mathematica is configured to detect the system's proxy settings when configuring how to connect to the internet to fetch data. A "bug" exists that will eventually crash Mathematica when the calling library is used. A workaround is to avoid this library call altogether by configuring Mathematica to "directly connect" to the internet. (''Edit > Preferences > Internet Connectivity > Proxy Settings''). This bug has been reported to Wolfram.<br />
<br />
=== Mathematica 10 ===<br />
<br />
[[Install]] {{AUR|mathematica}} (need historical version). The {{ic|Mathematica_10.XX.YY_LINUX.sh}} installation script is required; you will need to download this separately from Wolfram.com, your university, etc. You will also need an activation key.<br />
<br />
=== Mathematica 11 ===<br />
<br />
[[Install]] {{AUR|mathematica}}. Obtain {{ic|Mathematica_11.XX.YY_LINUX.sh}} from Wolfram Research, along with an activation key. Link (copy) the {{ic|Mathematica_11.XX.YY_LINUX.sh}} script to the package build directory (in the case of the [[AUR_helpers|AUR helper]] {{AUR|yay}} this is by default {{ic|~/.cache/yay/mathematica/}}). Successful install may throw non-critical errors: xdg-icon-resource, mkdir, xdg-desktop-menu. For more details see the [https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=mathematica mathematica PKGBUILD file]<br />
<br />
Mathematica 11 automatically creates a document folder 'Wolfram Mathematica' in [https://reference.wolfram.com/language/ref/$UserDocumentsDirectory.html $UserDocumentsDirectory], which is set by Mathematica according to [[XDG user directories]].<br />
<br />
== Troubleshooting == <br />
<br />
=== Missing symbols ===<br />
<br />
If you have font rendering problems where certain symbols do not show up (i.e. {{ic|/}} appears as a square), try uninstalling {{Pkg|font-mathematica}}.<br />
<br />
Also, try [http://mathematica.stackexchange.com/questions/1158/invisible-conjugate-glyph-in-the-linux-frontend this] solution. It also states the issue is fixed with Mathematica version 9.<br />
<br />
Try having applications use anti-aliasing. <br />
For KDE: ''System Settings > Application Appearance > Fonts > Use anti-aliasing (Enabled)''<br />
<br />
=== HiDPI / Retina Screens ===<br />
<br />
If you have a [[HiDPI]] screen, such as an Apple Retina display, and the main text in Mathematica looks small when you open it, this can be fixed:<br />
<br />
* Go to ''Edit → Preferences''<br />
* From the ''Advanced'' tab, click ''Open Option Inspector''<br />
* In the tree on the right, go to ''Formatting Options → Font Options → Font Properties''<br />
* Change the value for ''"ScreenResolution"'' to double its current setting, e.g. 72 → 144. You can also use <code>xdpyinfo | grep resolution</code> to get a more precise number (which will need to be doubled).<br />
<br />
=== Conflicts with system libraries ===<br />
<br />
The Mathematica package includes a number of it's own libraries, located in <INSTALL_DIR>/SystemFiles/Libraries/Linux-x86-64. They may lead to some compatibility issues and fallback to the system versions of some of these libraries may be necessary.<br />
<br />
==== Symbol lookup error: /usr/lib/libfontconfig.so.1: undefined symbol: FT_Done_MM_Var ====<br />
<br />
Force Mathematica to use the system version of the freetype library.<br />
<br />
# cd <INSTALL_DIR>/SystemFiles/Libraries/Linux-x86-64<br />
# mv libfreetype.so.6 libfreetype.so.6.old<br />
<br />
==== Mathematica/11.3/SystemFiles/Libraries/Linux-x86-64/libz.so.1: version `ZLIB_1.2.9' not found (required by /usr/lib/libpng16.so.16) ====<br />
<br />
Force Mathematica to use the system version of the zlib library.<br />
<br />
# cd <INSTALL_DIR>/SystemFiles/Libraries/Linux-x86-64<br />
# mv libz.so.1 libz.so.1.old<br />
<br />
== See also ==<br />
<br />
* [http://www.wolfram.com/mathematica/ Official site]<br />
* [http://www.wolfram.com/support/ Official Support]</div>Ondrianhttps://wiki.archlinux.org/index.php?title=Mathematica&diff=557942Mathematica2018-12-01T12:53:16Z<p>Ondrian: /* Mathematica 11 */ Describe how to provide the installation script</p>
<hr />
<div>[[Category:Numerical analysis]]<br />
[[it:Mathematica]]<br />
[[ja:Mathematica]]<br />
[[zh-hans:Mathematica]]<br />
{{Related articles start}}<br />
{{Related|Scientific Applications}}<br />
{{Related|Sage-mathematics}}<br />
{{Related|Matlab}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Wolfram Mathematica|Mathematica]] is a commercial program used in scientific, engineering and mathematical fields. Here we explain how to install it.<br />
<br />
== Installation ==<br />
<br />
Since Mathematica is a non-free application and upgrades may incur costs, this section lists instructions for different available versions. <br />
<br />
=== Mathematica 6 ===<br />
<br />
==== Mounting iso ====<br />
<br />
One way to mount the Mathematica {{ic|.iso}} is to create a {{ic|/media/iso}} mount directory and add the following line to the [[fstab]]:<br />
/''location/of/mathematica.iso'' /media/iso iso9660 exec,ro,user,noauto,loop=/dev/loop0 0 0<br />
Now you can mount it with:<br />
# mount /media/iso<br />
<br />
==== Running the Installer ====<br />
<br />
You can start the installer by navigating to:<br />
/Unix/Installer<br />
Run ''MathInstaller'' with:<br />
sh ./MathInstaller<br />
{{Note|If you do not place the "sh" in front, then you will get an error about a bad interpreter.}}<br />
<br />
==== Fonts ====<br />
<br />
Add the directories containing Type1 and BDF fonts to your FontPath.<br />
<br />
=== Mathematica 7 ===<br />
<br />
Mathematica 7 is much easier to install.<br />
<br />
tar xf Mathematica-7.0.1.tar.gz<br />
cd Unix/Installer<br />
./MathInstaller<br />
<br />
Follow instructions.<br />
<br />
For KDE users, the Mathematica icon may appear in the ''Lost & Found'' category. To solve this, execute the following as root:<br />
<br />
# ln -s /etc/xdg/menus/applications-merged /etc/xdg/menus/kde-applications-merged<br />
<br />
=== Mathematica 8 ===<br />
<br />
An issue with Mathematica 8 is a reproducible crash when performing WolframAlpha[] functions. By default, Mathematica is configured to detect the system's proxy settings when configuring how to connect to the internet to fetch data. A "bug" exists that will eventually crash Mathematica when the calling library is used. A workaround is to avoid this library call altogether by configuring Mathematica to "directly connect" to the internet. (''Edit > Preferences > Internet Connectivity > Proxy Settings''). This bug has been reported to Wolfram.<br />
<br />
=== Mathematica 10 ===<br />
<br />
[[Install]] {{AUR|mathematica}} (need historical version). The {{ic|Mathematica_10.XX.YY_LINUX.sh}} installation script is required; you will need to download this separately from Wolfram.com, your university, etc. You will also need an activation key.<br />
<br />
=== Mathematica 11 ===<br />
<br />
[[Install]] {{AUR|mathematica}}. Obtain {{ic|Mathematica_11.XX.YY_LINUX.sh}} from Wolfram Research, along with an activation key. Link (copy) the {{ic|Mathematica_11.XX.YY_LINUX.sh}} script to the package build directory (in the case of the [[AUR_helpers|AUR helper]] {{AUR|yay}} this is by default {{ic|~/.cache/yay/mathematica/}}). Successful install may throw non-critical errors: xdg-icon-resource, mkdir, xdg-desktop-menu. For more details see the [https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=mathematica]<br />
<br />
Mathematica 11 automatically creates a document folder 'Wolfram Mathematica' in [https://reference.wolfram.com/language/ref/$UserDocumentsDirectory.html $UserDocumentsDirectory], which is set by Mathematica according to [[XDG user directories]].<br />
<br />
== Troubleshooting == <br />
<br />
=== Missing symbols ===<br />
<br />
If you have font rendering problems where certain symbols do not show up (i.e. {{ic|/}} appears as a square), try uninstalling {{Pkg|font-mathematica}}.<br />
<br />
Also, try [http://mathematica.stackexchange.com/questions/1158/invisible-conjugate-glyph-in-the-linux-frontend this] solution. It also states the issue is fixed with Mathematica version 9.<br />
<br />
Try having applications use anti-aliasing. <br />
For KDE: ''System Settings > Application Appearance > Fonts > Use anti-aliasing (Enabled)''<br />
<br />
=== HiDPI / Retina Screens ===<br />
<br />
If you have a [[HiDPI]] screen, such as an Apple Retina display, and the main text in Mathematica looks small when you open it, this can be fixed:<br />
<br />
* Go to ''Edit → Preferences''<br />
* From the ''Advanced'' tab, click ''Open Option Inspector''<br />
* In the tree on the right, go to ''Formatting Options → Font Options → Font Properties''<br />
* Change the value for ''"ScreenResolution"'' to double its current setting, e.g. 72 → 144. You can also use <code>xdpyinfo | grep resolution</code> to get a more precise number (which will need to be doubled).<br />
<br />
=== Conflicts with system libraries ===<br />
<br />
The Mathematica package includes a number of it's own libraries, located in <INSTALL_DIR>/SystemFiles/Libraries/Linux-x86-64. They may lead to some compatibility issues and fallback to the system versions of some of these libraries may be necessary.<br />
<br />
==== Symbol lookup error: /usr/lib/libfontconfig.so.1: undefined symbol: FT_Done_MM_Var ====<br />
<br />
Force Mathematica to use the system version of the freetype library.<br />
<br />
# cd <INSTALL_DIR>/SystemFiles/Libraries/Linux-x86-64<br />
# mv libfreetype.so.6 libfreetype.so.6.old<br />
<br />
==== Mathematica/11.3/SystemFiles/Libraries/Linux-x86-64/libz.so.1: version `ZLIB_1.2.9' not found (required by /usr/lib/libpng16.so.16) ====<br />
<br />
Force Mathematica to use the system version of the zlib library.<br />
<br />
# cd <INSTALL_DIR>/SystemFiles/Libraries/Linux-x86-64<br />
# mv libz.so.1 libz.so.1.old<br />
<br />
== See also ==<br />
<br />
* [http://www.wolfram.com/mathematica/ Official site]<br />
* [http://www.wolfram.com/support/ Official Support]</div>Ondrianhttps://wiki.archlinux.org/index.php?title=LightDM&diff=540591LightDM2018-09-10T11:40:56Z<p>Ondrian: /* Installation */ package removed</p>
<hr />
<div>[[Category:Display managers]]<br />
[[es:LightDM]]<br />
[[fr:LightDM]]<br />
[[ja:LightDM]]<br />
[[ru:LightDM]]<br />
[[zh-hans:LightDM]]<br />
{{Related articles start}}<br />
{{Related|Display manager}}<br />
{{Related|GDM}}<br />
{{Related|LXDM}}<br />
{{Related articles end}}<br />
<br />
[http://www.freedesktop.org/wiki/Software/LightDM LightDM] is a cross-desktop [[display manager]]. Its key features are:<br />
* Cross-desktop - supports different desktop technologies.<br />
* Supports different display technologies (X, Mir, Wayland ...).<br />
* Lightweight - low memory usage and high performance.<br />
* Supports guest sessions.<br />
* Supports remote login (incoming - XDMCP, VNC, outgoing - XDMCP, pluggable).<br />
* Comprehensive test suite.<br />
* Low code complexity.<br />
<br />
More details about LightDM's design can be found [http://www.freedesktop.org/wiki/Software/LightDM/Design here].<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|lightdm}}.<br />
{{Tip|Stable releases are even-numbered (1.8, 1.10) while development releases are odd-numbered (1.9, 1.11). These development releases are available with {{AUR|lightdm-devel}}. Also available is {{AUR|lightdm-git}}.}}<br />
<br />
=== Greeter===<br />
<br />
You will probably want to install a greeter. A greeter is a GUI that prompts the user for credentials, lets the user select a session, and so on. It is possible to use LightDM without a greeter, but only if an automatic login is configured, otherwise you will need to install {{pkg|xorg-server}} and one of the greeter packages below.<br />
<br />
The official repositories contain the following greeters:<br />
* {{Pkg|lightdm-gtk-greeter}}: this is the '''default''' greeter LightDM attempts to use when started unless configured to do otherwise.<br />
* lightdm-deepin-greeter ({{Pkg|deepin-session-ui}}): A greeter from the [[Deepin]] project.<br />
<br />
Other alternative greeters are available in the [[AUR]]:<br />
* {{AUR|lightdm-slick-greeter}}: A GTK+ Based greeter that is preferred over the {{Pkg|lightdm-gtk-greeter}} by distro creators<br />
* {{AUR|lightdm-webkit2-greeter}}: A greeter that uses Webkit2 for theming. It supersedes {{AUR|lightdm-webkit-greeter}}.<br />
* {{AUR|lightdm-unity-greeter}}: The greeter used by Ubuntu's [[Unity]].<br />
* {{AUR|lightdm-pantheon-greeter}}: A greeter from the elementary OS project.<br />
* {{AUR|lightdm-mini-greeter}}: A minimal, configurable, single-user greeter.<br />
<br />
You can set the default greeter by changing the {{ic|[Seat:*]}} section of the LightDM configuration file, like so:<br />
<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
[Seat:*]<br />
...<br />
greeter-session=lightdm-''yourgreeter''-greeter<br />
...<br />
}}<br />
<br />
One way to check which greeters are available is to list the files in the {{ic|/usr/share/xgreeters}} directory; each ''.desktop'' file represents an available greeter. In this example, the {{ic|lightdm-gtk-greeter}} and {{ic|lightdm-kde-greeter}} greeters are available:<br />
$ ls -1 /usr/share/xgreeters/<br />
lightdm-gtk-greeter.desktop<br />
lightdm-kde-greeter.desktop<br />
<br />
== Enabling LightDM ==<br />
<br />
Make sure to [[enable]] {{ic|lightdm.service}} so LightDM will be started at boot, see also [[Display manager#Loading the display manager]].<br />
<br />
== Command line tool ==<br />
<br />
LightDM offers a command line tool, {{ic|dm-tool}}, which can be used to lock the current seat, switch sessions, etc, which is useful with 'minimalist' window managers and for testing. To see a list of available commands, execute:<br />
$ dm-tool --help<br />
<br />
=== User switching ===<br />
<br />
{{Accuracy|Is this warning inappropriate? Don't {{ic|dm-tool lock}} and {{ic|dm-tool switch-to-greeter}} do the equivalent of calling {{ic|loginctl lock-session}}? If your screen locker doesn't register with ''logind'' then there's nothing {{ic|dm-tool ...}} can do - but that's not LightDM's fault. This issue is well known and touched upon [[List_of_applications#Screen_lockers|here]] and [[XScreenSaver#Lock_on_suspend|here]].}}<br />
<br />
{{Warning|1=The use of lightDM's built-in screen lockers like {{ic|dm-tool lock}} or {{ic|dm-tool switch-to-greeter}} [https://bbs.archlinux.org/viewtopic.php?pid=1712213#p1712213 are '''not''' recommended]. Use [[#Lock the screen using light-locker|light-locker]] or something from [[List of applications/Security#Screen lockers]].}}<br />
<br />
LightDM's ''dm-tool'' command can be used to allow multiple users to be logged in on separate ttys. The following will send a signal requesting that the current session be locked and then will initiate a switch to LightDM's greeter, allowing a new user to log in to the system.<br />
<br />
$ dm-tool switch-to-greeter<br />
<br />
== Testing ==<br />
<br />
First, [[install]] {{Pkg|xorg-server-xephyr}} from the [[official repositories]].<br />
<br />
Then, run LightDM as an X application:<br />
$ lightdm --test-mode --debug<br />
<br />
== Optional configuration and tweaks ==<br />
<br />
LightDM can be configured by modifying its config file, {{ic|/etc/lightdm/lightdm.conf}}.<br />
<br />
Some greeters have their own configuration files. For example:<br />
<br />
{{Pkg|lightdm-gtk-greeter}}: {{ic|/etc/lightdm/lightdm-gtk-greeter.conf}}<br />
<br />
{{AUR|lightdm-webkit2-greeter}}: {{ic|/etc/lightdm/lightdm-webkit2-greeter.conf}}<br />
<br />
{{Pkg|lightdm-kde-greeter}}: {{ic|/etc/lightdm/lightdm-kde-greeter.conf}}<br />
<br />
=== Changing background images/colors ===<br />
<br />
You can set the background to a hex color or an image. Some greeters offer more robust background options like background selection from the login screen, random backgrounds, etc.<br />
<br />
==== GTK+ greeter ====<br />
<br />
You can use the {{Pkg|lightdm-gtk-greeter-settings}} gui.<br />
<br />
Users wishing to customize the wallpaper on the greeter screen need to edit {{ic|/etc/lightdm/lightdm-gtk-greeter.conf}} and define the {{ic|background}} variable under the {{ic|[greeter]}} section. For example:<br />
{{hc|/etc/lightdm/lightdm-gtk-greeter.conf|2=<br />
[greeter]<br />
background=/usr/share/pixmaps/black_and_white_photography-wallpaper-1920x1080.jpg<br />
}}<br />
<br />
{{Note|It is recommended to place the PNG or JPG file in {{ic|/usr/share/pixmaps}} since the LightDM user needs read access to the wallpaper file.}}<br />
<br />
===== GTK3 Theme =====<br />
GTK3 themes can be specified with the {{ic|theme-name}} variable in the {{ic|[greeter]}} section of {{ic|/etc/lightdm/lightdm-gtk-greeter.conf}} For example, {{ic|1=theme-name=Adwaita-dark}}.<br />
<br />
==== Webkit2 greeter ====<br />
<br />
The {{AUR|lightdm-webkit2-greeter}} allows you to choose a background image directly on the login screen. It also offers an option to display a random image each time it starts. By default, images are sourced from {{ic|/usr/share/backgrounds}}. You can change the background images directory by editing {{ic|lightdm-webkit2-greeter.conf}}. For example:<br />
{{hc|/etc/lightdm/lightdm-webkit2-greeter.conf|2=<br />
[branding]<br />
background_images = /usr/share/backgrounds<br />
}}<br />
<br />
{{Note|The background images directory must be accessible to the LightDM user so it should not be located anywhere under {{ic|/home}}. }}<br />
<br />
==== Unity greeter ====<br />
<br />
Users using the {{AUR|lightdm-unity-greeter}} must edit the {{ic|/usr/share/glib-2.0/schemas/com.canonical.unity-greeter.gschema.xml}} file and then execute:<br />
# glib-compile-schemas /usr/share/glib-2.0/schemas/<br />
<br />
According to [https://bbs.archlinux.org/viewtopic.php?id=149945 this] page.<br />
<br />
==== KDE greeter ====<br />
<br />
Go to ''System Settings > Login Screen (LightDM)'' and change the background image for your theme.<br />
<br />
Alternatively, you can edit the {{ic|Background}} variable in {{ic|lightdm-kde-greeter.conf}} :<br />
<br />
{{hc|/etc/lightdm/lightdm-kde-greeter.conf|2=<br />
[greeter]<br />
theme-name=classic<br />
<br />
[greeter-settings]<br />
Background=/usr/share/archlinux/wallpaper/archlinux-underground.jpg<br />
BackgroundKeepAspectRatio=true<br />
GreetMessage=Welcome to %hostname%<br />
}}<br />
<br />
==== Slick Greeter ====<br />
<br />
Use the {{AUR|lightdm-settings}} GUI <br />
<br />
=== Changing your avatar ===<br />
<br />
{{Tip|If you are using KDE, you can change your avatar in KDE System Settings.}}<br />
<br />
First, make sure the {{pkg|accountsservice}} package from the [[official repositories]] is installed, then set it up as follows, replacing {{ic|''username''}} with the desired user's login name.<br />
<br />
* Create the file {{ic|/var/lib/AccountsService/icons/''username''.png}} using a 96x96 PNG image file. Different image file formats are possible too, e.g., JPEG.<br />
<br />
* Edit or create the account settings file {{ic|/var/lib/AccountsService/users/''username''}}, and add the lines<br />
<br />
[User]<br />
Icon=/var/lib/AccountsService/icons/''username''.png<br />
<br />
The filename here should point to the icon created in the first step, so adjust the filename extension if necessary.<br />
<br />
{{Note|Make sure that both created files have 644 permissions, use [[chmod]] to correct them.}}<br />
<br />
=== Sources of Arch-centric 64x64 icons ===<br />
<br />
The {{AUR|archlinux-artwork}} package contains some nice examples that install to {{ic|/usr/share/archlinux/icons}} and that can be copied to {{ic|/usr/share/icons/hicolor/64x64/devices}} as follows:<br />
<br />
# find /usr/share/archlinux/icons -name "*64*" -exec cp {} /usr/share/icons/hicolor/64x64/devices \;<br />
<br />
After copying, the {{AUR|archlinux-artwork}} package can be removed.<br />
<br />
=== Enabling autologin ===<br />
<br />
Edit the LightDM configuration file and ensure these lines are uncommented and correctly configured:<br />
<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
[Seat:*]<br />
autologin-user=''username''<br />
}}<br />
<br />
You must be part of the {{ic|autologin}} group to be able to login automatically without entering your password:<br />
<br />
# groupadd -r autologin<br />
# gpasswd -a ''username'' autologin<br />
<br />
LightDM logs in using the session specified in the {{ic|~/.dmrc}} of the user getting logged in automatically. To override this file, specify {{ic|autologin-session}} in {{ic|lightdm.conf}}:<br />
<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
[Seat:*]<br />
autologin-user=''username''<br />
autologin-session=''session''<br />
}}<br />
<br />
You will also need to ensure you have the {{Pkg|accountsservice}} package installed, otherwise LightDM will fail to start, and running it from the command line will show {{ic|Error getting user list from org.freedesktop.Accounts}}.<br />
<br />
{{Note|GNOME users, and by extension any gnome-keyring user will have to set up a blank password to their keyring for it to be unlocked automatically.}}<br />
<br />
=== Enabling interactive passwordless login ===<br />
<br />
LightDM goes through PAM so you must configure the lightdm configuration of PAM:<br />
<br />
{{hc|/etc/pam.d/lightdm|2=<br />
#%PAM-1.0<br />
'''auth sufficient pam_succeed_if.so user ingroup nopasswdlogin'''<br />
auth include system-login<br />
...<br />
}}<br />
<br />
You must then also be part of the {{ic|nopasswdlogin}} group to be able to login interactively without entering your password:<br />
<br />
# groupadd -r nopasswdlogin<br />
# gpasswd -a ''username'' nopasswdlogin<br />
<br />
{{Note|GNOME users, and by extension any gnome-keyring user may have to follow the instructions at the end of the previous section on enabling autologin.}}<br />
<br />
To create a new user account that logs in automatically and additionally able to login again without a password the user can be created with supplementary membership of both groups, e.g.:<br />
<br />
# useradd -mG autologin,nopasswdlogin -s /bin/bash ''username''<br />
<br />
=== Hiding system and services users ===<br />
To prevent system users from showing-up in the login, install the optional dependency {{Pkg|accountsservice}}, or add the user names to {{ic|/etc/lightdm/users.conf}} under {{ic|hidden-users}}. The first option has the advantage of not needing to update the list when more users are added or removed.<br />
<br />
=== Migrating from SLiM ===<br />
<br />
{{Merge|Display Manager|Not LightDM specific (or even SLiM specific for that matter as [[XDM]] also uses [[xinitrc]]). Perhaps this merits a one-liner somewhere on the [[Display Manager]] page?}}<br />
<br />
Move the contents of [[xinitrc]] to [[xprofile]], removing the call to start the [[window manager]] or [[desktop environment]].<br />
<br />
=== Login using ~/.xinitrc ===<br />
<br />
See [[Display manager#Run ~/.xinitrc as a session]].<br />
<br />
=== NumLock on by default ===<br />
<br />
Install the {{Pkg|numlockx}} package and then edit {{ic|/etc/lightdm/lightdm.conf}}:<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
[Seat:*]<br />
greeter-setup-script=/usr/bin/numlockx on<br />
}}<br />
<br />
=== Default session ===<br />
<br />
Lightdm, like other DMs, stores the last-selected xsession in {{ic|~/.dmrc}}. See [[Display manager#Session configuration]] for more info.<br />
<br />
=== Adjusting the login window's position ===<br />
<br />
==== GTK+ greeter ====<br />
<br />
Users need to edit {{ic|/etc/lightdm/lightdm-gtk-greeter.conf}} and enter a value for the {{ic|position}} variable. It accepts {{ic|x}} and {{ic|y}} values, either absolute (in pixels) or relative (in percent). Each value can also have an additional anchor location for the window, {{ic|start}}, {{ic|center}} and {{ic|end}} separated from the value by a comma.<br />
<br />
Example:<br />
<br />
position=200,start 50%,center<br />
<br />
=== VNC Server ===<br />
Lightdm can also be used to connect to via VNC. Make sure to install {{pkg|tigervnc}} on the server side and optionally as your VNC client on the client PC.<br />
<br />
Setup an authentication password on the server as root:<br />
<br />
# vncpasswd /etc/vncpasswd<br />
<br />
Edit the LightDM configuration file as shown below. Note that {{ic|listen-address}} configures the VNC to only listen to connections from localhost. This is used to only allow connections via [[TigerVNC#On_the_client|SSH and port forwarding]]. On the SSH client, make sure that you use {{ic|localhost:5900}} for the tunnel destination; using {{ic|127.0.0.1:5900}} or {{ic|::1:5900}} is not reliable on dual stack network connections. If you want to allow insecure connections you can disable this setting.<br />
<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
[VNCServer]<br />
enabled=true<br />
command=Xvnc -rfbauth /etc/vncpasswd<br />
port=5900<br />
listen-address=localhost<br />
width=1024<br />
height=768<br />
depth=24<br />
}}<br />
<br />
Now open an SSH tunnel and connect to localhost as described in [[TigerVNC#On the client]].<br />
<br />
{{Note|If you get a blank screen upon opening the VNC connection, try a different LightDM greeter.}}<br />
<br />
=== Lock the screen using light-locker ===<br />
{{Pkg|light-locker}} is a simple screen locker using LightDM to authenticate the user. Once it is installed and running you can lock your session using<br />
$ light-locker-command -l<br />
This requires {{ic|light-locker}} to be started at the beginning of your session - see [[Autostarting]].<br />
<br />
== Troubleshooting ==<br />
If you encounter consistent screen flashing and ultimately no LightDM on boot, ensure that you have defined the greeter correctly in LightDM's config file. And if you have correctly defined the GTK greeter, make sure the {{ic|xsessions-directory}} (default: {{ic|/usr/share/xsessions}}) exists and contains at least one .desktop file.<br />
<br />
The same error can happen on lightdm startup if the last used session is not available anymore (eg. you last used gnome and then removed the gnome-session package): the easiest workaround is to temporarily restore the removed package. Another solution might be:<br />
<br />
# dbus-send --system --type=method_call --print-reply --dest=org.freedesktop.Accounts /org/freedesktop/Accounts/User1000 org.freedesktop.Accounts.User.SetXSession string:xfce<br />
<br />
This example sets the session "xfce" as default for the user 1000.<br />
<br />
=== Wrong locale displayed ===<br />
<br />
In case of your locale not being displayed correctly in Lightdm add your locale to {{ic|/etc/environment}}<br />
LANG=pt_PT.utf8<br />
<br />
Alternatively if you want LightDM and its greeters to be in a language other than your set system locale, you can use the {{ic|1=Environment=}} option in [[Systemd#Drop-in files]].<br />
<br />
=== Missing icons with GTK greeter ===<br />
<br />
If you are using {{Pkg|lightdm-gtk-greeter}} as a greeter and it shows placeholder images as icons, make sure valid icon themes and themes are installed and configured. Check the following file:<br />
<br />
{{hc|/etc/lightdm/lightdm-gtk-greeter.conf|2=<br />
[greeter]<br />
theme-name=mate # this should be the name of a directory under /usr/share/themes/<br />
icon-theme-name=mate # this should be the name of a fully featured icons set directory under /usr/share/icons/<br />
}}<br />
<br />
=== LightDM freezes on login attempt ===<br />
<br />
You may find that after entering the correct username and password and attempting to log in, LightDM freezes and you are unable to continue to the desktop. To fix the issue, reinstall the {{Pkg|gdk-pixbuf2}} package. See [https://bbs.archlinux.org/viewtopic.php?id=179031 this forum thread].<br />
<br />
=== LightDM displaying in wrong monitor ===<br />
<br />
If you are using multiple monitors, LightDM may display in the wrong one (e.g. if your primary monitor is on the right). To force the LightDM login screen to display on a specific monitor, edit {{ic|/etc/lightdm/lightdm.conf}} and change the ''display-setup-script'' parameter like this:<br />
{{hc|/etc/lightdm/lightdm.conf|2=<br />
display-setup-script=xrandr --output ''HDMI1'' --primary<br />
}}<br />
<br />
Replace ''HDMI1'' with your real monitor ID, which you can find from '''xrandr''' command output.<br />
<br />
Alternatively, if you are using the GTK+ greeter, you can edit {{ic|/etc/lightdm/lightdm-gtk-greeter.conf}} and add the ''active-monitor'' parameter like this:<br />
{{hc|/etc/lightdm/lightdm-gtk-greeter.conf|2=<br />
[greeter]<br />
active-monitor=0<br />
}}<br />
<br />
Replace 0 with the desired display number.<br />
<br />
=== LightDM does not appear or monitor only displays TTY output===<br />
<br />
It may happen that your system boots so fast that LightDM service is started before your graphics drivers are properly loaded. If this is your case, you will want to add the following config to your lightdm.conf file:<br />
<br />
[LightDM]<br />
logind-check-graphical=true<br />
<br />
This setting will tell LightDM to wait until graphics devices are ready before spawning greeters/autostarting sessions on them.<br />
<br />
=== Pulseaudio not starting automatically ===<br />
<br />
See [[PulseAudio#Running]].<br />
<br />
=== Long pause before LightDM shows up when home is encrypted ===<br />
<br />
Some LightDM themes try to access the user avatar located in HOME. If your HOME is encrypted, LightDM cannot access it and hangs. To prevent this from happening, you can either:<br />
<br />
* Set your avatar as explained in [[#Changing your avatar]]<br />
* for {{Pkg|lightdm-gtk-greeter}} only: {{Ic|<nowiki>hide-user-image = true</nowiki>}} in {{Ic|/etc/lightdm/lightdm-gtk-greeter.conf}}<br />
<br />
=== Boot hangs on "[ OK ] Reached target Graphical Interface." ===<br />
<br />
There is a possibility that user and group lookups fail if you modified /etc/nsswitch.conf. That happens when:<br />
<br />
* nsswitch.conf group: includes {{Ic|<nowiki>ldap</nowiki>}} without setting {{Ic|<nowiki>nss_initgroups_ignoreusers ALLLOCAL</nowiki>}} in {{Ic|<nowiki>/etc/nslcd.conf</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [https://wiki.ubuntu.com/LightDM Ubuntu Wiki article]<br />
* [http://wiki.gentoo.org/wiki/LightDM Gentoo Wiki article]<br />
* [https://launchpad.net/lightdm Launchpad Page] obsolete<br />
* [http://www.mattfischer.com/blog/?tag=lightdm LightDM blog]<br />
* [https://github.com/CanonicalLtd/lightdm LightDM on GitHub]</div>Ondrian