From 0b48532c520d88f1c782be4c7b7feb1b53896f98 Mon Sep 17 00:00:00 2001 From: Stefan Melmuk <509385+stefan0xC@users.noreply.github.com> Date: Tue, 24 Jun 2025 00:52:41 +0200 Subject: [PATCH] clarify a few statements and add some sections to make it more readable --- Using-custom-website-icons.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/Using-custom-website-icons.md b/Using-custom-website-icons.md index df39bbc..979171b 100644 --- a/Using-custom-website-icons.md +++ b/Using-custom-website-icons.md @@ -9,18 +9,24 @@ If you want to add custom icons for your website entries you can place them in t ![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 service (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. +## How the icon cache expiration works -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. +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. You can disable the expiration feature by setting `ICON_CACHE_TTL=0` so that Vaultwarden will keep any existing icon locally cached forever. + +If setting `ICON_CACHE_TTL=0` is not an option for you (because you want to get new icons for most websites and only provide a few custom ones), you can also write a cron job that regularly calls `touch` on your custom placed icons so their modification time is kept fresh and they won't expire. + +> [!IMPORTANT] +By default `ICON_CACHE_TTL` is set to 259200 seconds so if you don't disable expiration or regularly update the modification time any manually placed icon will be ignored and possible overwritten after 30 days. ### 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 you have not disabled icon download (`DISABLE_ICON_DOWNLOAD`) Vaultwardens `internal` icon service 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. +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 file is removed automatically on a new request when the miss file has expired. (Expired in this case means its age is larger than `ICON_CACHE_NEGTTL` seconds which defaults to 3 days.) -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 +> [!IMPORTANT] +As long as there is an `.miss` file (that has not yet expired) Vaultwarden will always serve the fallback icon even if there is a valid icon. So remove any corresponding miss file for any custom icon you have created or updated its modification time. + +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) due to security concerns. You can also further configure which hosts Vaultwarden should block additionally by specifying a `HTTP_REQUEST_BLOCK_REGEX`. \ No newline at end of file