sdgoij/vaultwarden
1
0
Fork 0
mirror of https://github.com/dani-garcia/vaultwarden.git synced 2026-01-16 20:50:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

explain a bit about the icon service and how to add custom icons

Stefan Melmuk
2025-06-23 23:15:45 +02:00
parent a2b849dba9
commit 7deb5c4e17
1 changed files with 26 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
Using-custom-website-icons.md Normal file

@@ -0,0 +1,26 @@
> [!NOTE]
This page is about the [website icons](https://bitwarden.com/help/website-icons/#using-website-icons) displayed next your entries (when using the `internal` icon service). If you want to customize the look of the web-vault you should refer to [Customize Vaultwarden CSS](Customize-Vaultwarden-CSS)
> [!IMPORTANT]
The clients will only request icons for entries where you have configured an Autofill URI.
Be aware that you can also turn off website icons in your client settings, in which case the client will not request icons from Vaultwarden.
If you want to add custom icons for your website entries you can place them in the location of the `ICON_CACHE_FOLDER` (which defaults to `data/icon_cache`). The naming is based on the specified IP or fully qualified domain name (FQDN) of your entry, i.e. what Bitwarden calls Hostname in [this graphic](https://bitwarden.com/help/uri-match-detection/#match-detection-options):
![bitwarden-uri-graphic](https://github.com/user-attachments/assets/47bdf0f1-46f9-41af-8030-d0f860e2a056)
This means the scheme and port will be ignored when requesting icons, so you can't provide different icons based on the port number.
If you are using the `internal` icon cache (the default) Vaultwarden will generally serve the icons from the `ICON_CACHE_FOLDER`.
While the web-vault supports a couple of image types like ICO, BMP, GIF, JPG, WEBP and PNG, the cached icons themselves are always named `<fqdn>.png` or `<IP>.png` (eg. `data/icon_cache/en.wikipedia.org.png`). So you should name your custom icons accordingly.
If an icon file already exists it will check its last modification time if it is outdated (which is configurable via `ICON_CACHE_TTL`). If it is expired, it will try to fetch a new icon instead of serving that icon. If you set `ICON_CACHE_TTL=0` Vaultwarden will not update an existing icon.
If setting `ICON_CACHE_TTL=0` is not an option for you, you can also write a cron job that regularly calls `touch` on a custom placed icon so its modification time is kept fresh and it won't expire.
### Website Icon Troubleshooting
If you have not disabled icon download (`DISABLE_ICON_DOWNLOAD`) Vaultwarden will download the requested icon from a given resource. This is done using a network request to the given domain / ip (disregarding the port). If your Vaultwarden server cannot make outgoing requests (e.g. because of missing internet access) downloading new icons will not work.
If fetching an icon fails (for whatever reason), Vaultwarden will create a `.miss` file in the `ICON_CACHE_FOLDER` and not try fetching an icon again and instead serve an fallback icon instead. The miss indicator file is removed automatically on a new request when it has expired. (Expired in this case means its age is larger than `ICON_CACHE_NEGTTL`.) As long as there is an `.miss` file (that has not expired) Vaultwarden will always serve the fallback icon even if there is a valid icon.
By default, Vaultwarden will also [block certain IP ranges](https://github.com/dani-garcia/vaultwarden/blob/9059437c35e35ab8eb7d1d4716bf13eec0a4ee64/src/util.rs#L776-L819) which it considers non-global (i.e. your private network). You can also further configure which hosts Vaultwarden should block additionaly by specifying a `HTTP_REQUEST_BLOCK_REGEX`.