dahjah/vaultwarden
1
0
Fork 0
mirror of https://github.com/dani-garcia/vaultwarden.git synced 2025-12-16 04:09:03 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

clarify a few statements and add some sections to make it more readable

Stefan Melmuk 2025-06-24 00:52:41 +02:00
parent 4a934f0b7f
commit 0b48532c52
1 changed files with 13 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
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 `<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.
## 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`.
> [!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`.