From 7deb5c4e17662f0ef6739c89c420c1766f5fbb90 Mon Sep 17 00:00:00 2001 From: Stefan Melmuk <509385+stefan0xC@users.noreply.github.com> Date: Mon, 23 Jun 2025 23:15:45 +0200 Subject: [PATCH] explain a bit about the icon service and how to add custom icons --- Using-custom-website-icons.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 Using-custom-website-icons.md diff --git a/Using-custom-website-icons.md b/Using-custom-website-icons.md new file mode 100644 index 0000000..423b449 --- /dev/null +++ b/Using-custom-website-icons.md @@ -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 `.png` or `.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`. \ No newline at end of file