PHPIndex

Learning how to handle a new application is not always easy. We’ve tried to make FreshRSS as intuitive as possible, but you might still need a little help to master the program.

This section will guide you to the pages you need to get started. The order is tailored to newcomers.

[After installing the application](../admins/03_Installation.md), the first step is to add some feeds. You have a few options:

1. [Add a feed manually](04_Subscriptions.md#adding-a-feed)
2. [Import an OPML or JSON file](04_Subscriptions.md#import-and-export)
3. [Use the bookmarklet](04_Subscriptions.md#use-bookmarklet)

Once you have added your feeds to FreshRSS, it is time to read them. There are three available reading modes:

1. [The normal view](03_Main_view.md#normal-view) enables you to quickly read new articles
2. [The global view](03_Main_view.md#global-view) shows you an overview of the status of your feeds in one glance
3. [The reader view](03_Main_view.md#reader-view) offers you a comfortable reading experience

Now that you’ve mastered basic use, it’s time to configure FreshRSS to improve your reading experience. It’s highly configurable, so it’s recommended to play around with them to find a configuration that suits you well. Here are a few resources to help you improve your daily FreshRSS experience:

* [Organize your feeds in categories](04_Subscriptions.md#feed-management)
* [Change the home page](05_Configuration.md#changing-the-view)
* [Choose the reading options](05_Configuration.md#reading-options)
* [Refresh feeds](09_refreshing_feeds.md)
* [Filter articles](10_filter.md) for a fast access to a selection
* [search for an article](10_filter.md#with-the-search-field) published some time ago
* [Access your feeds on a mobile device](06_Mobile_access.md)
* [Add some extensions](https://github.com/FreshRSS/Extensions)
* [Frequently asked questions](07_Frequently_Asked_Questions.md)
* [Receive articles instantly with WebSub](WebSub.md)

FreshRSS has a built-in engine that [scrapes a website to create an own feed](11_website_scraping.md).

# Views

FreshRSS has three primary viewing modes: Normal, Global, and Reader view.

## Normal view

Normal view will allow you to view articles in a compressed view. They can be separated by category or individual feed, or viewed in the "main stream" containing all feeds. Clicking a feed in the sidebar (mobile users will need to click the folder icon to open it) will open that feed’s view.

### Article List

By default, the normal view includes six items per article. From left to right:
* **Read status:** An envelope icon to show if the article has been read or not. Closed envelopes are unread, open envelopes are read. Clicking on the icon will toggle the read status.
* **Favourite status:** A star icon to show if the article has been favourited or not. Filled stars are favourited, empty stars are not. Clicking on the icon will toggle the favourite status.
* **Feed name:** The name of the feed that the article is from. Clicking the feed name will move to that feed’s view in normal view.
* **Article title:** The title of the article. Clicking will open the article for viewing within FreshRSS.
* **Article date/time:** The time the article was posted.
* **Link to original article:** A globe icon that can be clicked to go to the article on the original website.

### Normal View Sidebar

Clicking the gear icon next to an individual feed will display additional options for that feed.
* **Filter:** Run the defined filter to mark articles as read
* **Statistics:** View statistics about the feed
* **See website:** Open the feed’s website in another tab
* **Manage:** Configure the feed
* **Actualize:** Force-update the feed
* **Mark as read:** Mark all items in the feed as read

## Global view

Global view allows quick views of feed’s statuses at once. Feeds and categories are shown with the number of unread articles next to them. Clicking a feed’s name will open it in a view similar to normal view.

## Reader view

Reader view will display a feed will all articles already open for reading. Feeds can be switched by clicking the folder icon at the top to bring up the category/feed sidebar.

---
Read more:
* [Refreshing the feeds](./09_refreshing_feeds.md)
* [Filter the feeds and search](./10_filter.md)
* [User queries](./user_queries.md)

# Adding a feed

1. To add a feed, copy the URL of its RSS or Atom file (for instance, the Framablog RSS URL is `https://framablog.org/feed/`). FreshRSS is able to automatically find the address of the feed for websites that are declaring it in a standard way.
2. In FreshRSS, click the "**+**" button next to “Subscriptions management”.
3. Paste the URL in the “Feed URL” field.
4. (optional): You can select the category for your feed. By default, it will be in “Uncategorized”.
5. (optional): If the subscription requires credentials, you can enter them in the "HTTP username" and "HTTP password" fields.
6. (optional): You can set a timeout for the feed request.
7. (optional): You can choose to ignore SSL certificate errors (such as with self-signed certificates) by setting "Verify SSL security" to "No". This is not recommended, and it is better to either add the root certificate to the FreshRSS server or to fix the SSL certificate problems on the feed hosting server.

## Subscription management

The "Subscription management" submenu allows categories and feeds to be configured. Feeds can be moved between categories by drag-and-drop, or in the individual feed’s settings. Hovering over a feed/category will cause a gear icon to appear. Clicking the icon will bring up the settings for that item.

## Category Settings

### Information

* **Title:** Name of category
* **Display position:** Defines the order of categories. Lower numbers get priority, non-numbered items come last, and equally numbered items will sort by alphabetical order.

### Archiving

If "Purge Policy" has "By default" selected, then the [default purge policy](./05_Configuration.md) is used and the other options are not displayed. Category options will override the default policy, but they will not override feed-specific options.

## Feed Settings

These fields will be auto-filled when adding a feed, but they can be modified later. **Visibility** will define if the feed is displayed in the main feed, only in specific categories, or not at all.

### Archival

This section will let you override the default settings for feed archiving and update frequency.

### Login

Some feeds require a username/password submitted over HTTP. These usually aren’t needed for feeds.

### Advanced

#### Retrieve a truncated feed from within FreshRSS

This question comes up regularly, so we’ll try to clarify how one can retrieve a truncated RSS feed with FreshRSS. Please note that the process is absolutely not user friendly, but it works. :)

Please be aware that this way you’ll generate much more traffic to the originating sites, and they might block you accordingly. FreshRSS performance is also negatively affected, because you’ll have to fetch the full article content one by one. So it’s a feature to use sparingly!

The  "Article CSS selector on original website" corresponds to the "path" consisting of IDs and classes (which in HTML, matches the id and class attributes) to retrieve only the interesting part that corresponds to the article. Ideally, this path starts with an id (which is unique to the page). The basics are explained [here](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors).

##### Example: Rue89

To find this path, you have to go to the address of one of the truncated articles.
You look have to look for the "block" of HTML that corresponds to article content (in the source code!).

Here we find that the block that encompasses nothing but the content of the article is ```<div class="content clearfix">```. We’ll only use the `.content` class here. Nevertheless, as said above, it’s best to start the path with an id. If we go back to the parent block, we find ```<div id="article">``` and that’s perfect! The path will be ```#article .content```.

##### Add the corresponding classes to the article CSS path on the feed configuration page

Examples:

* Rue89: ```#article .content```
* PCINpact: ```#actu_content```
* Lesnumériques: ```article#body div.text.clearfix```
* Phoronix: ```#main .content```

##### Combining CSS Classes

Let’s say we have an article which contains ads, and we do not want to have those ads retrieved by FreshRSS. Example HTML:

```html
<div id="article">
<h2>wanted</h2>
<p class="content">wanted content</p>
<p class="ad">unwanted content</p>
<h2>wanted</h2>
<p class="content">wanted content</p>
<h2>wanted</h2>
<p class="ad">unwanted content</p>
<p class="content">wanted content</p>
</div>
```

In this case it’s possible to combine multiple CSS selectors with a comma: ```#article p.content, #article h2```

#### Retrieve a truncated feed with external tools

Complementary tools can be used to retrieve full article content, such as:

* [RSS-Bridge](https://github.com/RSS-Bridge/rss-bridge)
* [Full-Text RSS](https://bitbucket.org/fivefilters/full-text-rss)

### Filter

Articles can be automatically marked as read based on some search terms. See [filtering](./10_filter.md) for more information on how to create these filters.

## Import / export

See [SQLite export/import]( https://github.com/FreshRSS/FreshRSS/tree/edge/cli) as an alternative.

## Export

1. To export your list of feeds, go to “Subscriptions management”.
2. Click on “Import / export”
3. You can select for your export:
	1. the list of feeds
	2. labelled articles
	3. favourite articles
	4. and finally, you can select feeds you want to export (by default, all feeds are selected)
4. Click on “export”.

## Import

1. Go to the page “Import / export”.
2. Click on “Browse” and select your OPML or archive file on your computer.
3. Click on “Import”

> **Important**: you can not import directly a list of feeds from a text file.
> You need to convert it beforehand to _OPML_.
> Here is some tools you could use :
>
> * [Pandoc](https://pandoc.org/) available for most systems,
> * [OPML generator](https://opml-gen.ovh/) available online,
> * [txt2opml](https://alterfiles.com/convert/txt/opml) available online.

## Use bookmarklet

Bookmarklets are little scripts that you can execute to perform various tasks. FreshRSS offers a bookmarklet for subscribing to newsfeeds.

1. Open “Subscriptions management”.
2. Click on “Subscription tools”.
3. Drag the “Subscribe” button to your bookmark toolbar or right click and choose your browser’s “Bookmark link” action.

# Display

## Language

FreshRSS is currently available in 22 languages. After confirming your choice, the interface will be displayed in your preferred language.
Depending on the language chosen, parts of the interface may not be not translated yet. If you’re willing to help translate
the missing bits or would like to add a new language, please take a look at how you can [contribute to the project](../contributing.md#contribute-to-internationalization-i18n).

Some parts of FreshRSS are not translated and are not intended to be translated either. For now, this includes the logs visible in the application as well as the log generated by automatic update scripts.

Available languages are:

| Language (English name) | Language (Endonym) | Ordered by language code (ISO-639-1) |
|:------------------------|:-----------------------|:-------------------------------------|
| Czech                   | Čeština                | cs                                   |
| German                  | Deutsch                | de                                   |
| Greek                   | Ελληνικά               | el                                   |
| English                 | English                | en                                   |
| English (United States) | English (United States) | en-us                               |
| Spanish                 | Español                | es                                   |
| French                  | Français               | fr                                   |
| Hebrew                  | עברית                  | he                                   |
| Hungarian               | Magyar                 | hu                                   |
| Indonesian              | Bahasa Indonesia       | id                                   |
| Italian                 | Italiano               | it                                   |
| Japanese                | 日本語                  | ja                                   |
| Korean                  | 한국어                  | ko                                   |
| Latvian                 | Latviešu               | lv                                   |
| Dutch                   | Nederlands             | nl                                   |
| Occitan                 | Occitan                | oc                                   |
| Polish                  | Polski                 | pl                                   |
| Brazilian Portuguese    | Português (Brasil)     | pt-br                                |
| Russian                 | Русский                | ru                                   |
| Slovak                  | Slovenčina             | sk                                   |
| Turkish                 | Türkçe                 | tr                                   |
| Chinese (Simplified, People’s Republic of China) | 简体中文      | zh-cn                 |
| Chinese (Traditional, Taiwan) | 正體中文          | zh-tw                                |

## Theme

There’s no accounting for tastes, which is why FreshRSS offers 13 official themes:

| Theme       | designed by                                   | Notes                                                         |
|:--------------|:-------------------------------------------------------|:--------------------------------------------------------------|
| Alternative Dark | Ghost | |
| Ansum | Thomas Guesnon  | |
| ~~Blue Lagoon~~     |Mister aiR | Was removed with FreshRSS V1.22.0 |
| Dark | AD | |
| Dark pink | Miicat_47 | |
| Flat design | Marien Fressinaud | |
| Mapco | Thomas Guesnon  | |
| Nord theme | joelchrono12 | |
| Origine | Marien Fressinaud | (default theme) |
| Origine-compact | Kevin Papst | |
| Pafat | Plopoyop | |
| ~~Screwdriver~~ | Mister aiR | Was removed with FreshRSS V1.22.0 |
| Swage | Patrick Crandol | |

To select a theme, simply scroll through the themes and select one that strikes your fancy. After confirmation, the theme will be applied to the interface.

If you can’t find any themes you like, it’s always possible to [create your own](../developers/04_Frontend/02_Design.md) and [install it](../admins/11_Themes.md). For small theme changes, the official [CustomCSS extension](https://github.com/FreshRSS/Extensions) is recommended.

## Content width

Some people prefer short lines of text, while others prefer to maximize the available screen space. To satisfy the maximum number of people, it’s possible to customize the width of the displayed content. There are four settings available:

* **Fine** displays content up to a maximum width of 550 pixels
* **Medium** displays content up to a maximum width of 800 pixels
* **Large** displays content up to a maximum width of 1000 pixels
* **No limit** displays the content on 100% of the available space

## Article icons

Please note that this section only affects normal view.

![Article icons configuration](../img/users/configuration.article.icons.png)

Each article is rendered with a header (top line) and a footer (bottom line).
In that section, you can choose what will be displayed in those.

If you disable every item in the top line, you’ll still be able to see it since
it contains the feed name and the article title. But if you do the same thing for
the bottom line, it will be empty.

## HTML5 notification timeout

After automatically updating the feeds, FreshRSS can pop up a notification using the HTML5 notification API.

The duration of this notification can be set. By default, the value is 0.

## Show the navigation button

By default, FreshRSS displays buttons to ease the article navigation when browsing on mobile. The drawback is that they eat up some precious space.

![navigation button configuration](../img/users/configuration.navigation.button.png)

If you don’t use those buttons because you never browse on mobile or because you browse with gestures, you can disable them from the interface.

# Reading

## Number of articles per page

This setting defines the number of articles to display at once before needing to load more. In normal and reading view, more articles are loaded automatically. In global view, a button will appear at the bottom of the list.

## Articles to display

The status of articles to display when loading FreshRSS. "Adjust showing" will display only unread articles by default, but will display all articles when there are no unread articles to show.

## Use “lazy load” mode to load images

This will set images to load as they are viewed. This can save data, but will can cause images to load in later.

# Archival

## Archiving

These are the global options for fetching and retaining articles from feeds. They can be overridden by individual feed’s settings.

## Maintenance

This allows for purging/optimizing the current user’s articles in the database.

# Sharing

To make your life easier, you can share articles straight from FreshRSS.

At the moment, FreshRSS supports [20+ sharing services](08_sharing_services.md), ranging from self-hosted services (Shaarli, etc.) to proprietary services (Facebook, etc.).

By default, the sharing list is empty.
![Sharing configuration](../img/users/configuration.sharing.png)

To add a new item to the list, please follow the following simple steps:

1. Select the desired sharing method in the drop-down list.
1. Press the ```✚``` button to add it to the list.
1. Configure the method in the list. All  names can be modified in the display. Some methods need the sharing URL to be able to work properly (ex: Shaarli).
1. Submit your changes.

To remove an item from the list, follow those simple steps:

1. Press the ```❌``` button next to the share method you want to remove.
1. Submit your changes.


# Shortcuts

To ease the use of the application, FreshRSS comes with a lot of predefined keyboard shortcuts.
They allow actions to improve the user experience with a keyboard.

Of course, if you’re not satisfied with the key mapping, you can change you configuration to fit your needs.

There are 4 types of shortcuts:

1. Views: they allow switching views with ease.
1. Navigation: they allow navigation through articles, feeds, and categories.
1. Article actions: they allow interactions with an article, like sharing or opening it on the original web-site.
1. Other actions: they allow other interactions with the application, like opening the user queries menu or accessing the documentation.

It’s worth noting that the share article action has two levels. Once you press the shortcut, a menu containing all the share options opens.
To choose one share option, you need to select it by its number. When there is only one option, it’s selected automatically though.

The same process applies to the user queries.

Be aware that there is no validation on the selected shortcuts.
This means that if you assign a shortcut to more than one action, you’ll end up with some unexpected behavior.

# User queries

You can configure your [user queries](./user_queries.md) in that section.

# Profile

You can change your email address or password here. The authentication token is required for accessing the aggregated RSS feed for a user. A blank token will disable accessing the RSS feed without being logged in.

# Extensions

Extensions can be managed from this menu. Note that while extensions can be removed from the web interface, they cannot be added from it.

Some extensions have configurations and these can be changed in the manage page, which opens with the button near the name of the extension.

## User CSS

It gives ability to create user-specific CSS rules to apply in addition of the actual theme.

### Example: Getting rid of Top Menu Items

The Top Menu within the mobile view might look a little bit cluttered, depending on the theme. The following CSS rules allow to hide unnecessary top menu buttons or input boxes.

```css
@media (max-width: 840px)
{
    /* Hides "Actions" Menu in Mobile View */
    #nav_menu_actions {
        display: none;
    }

    /* Hides "Views" Menu in Mobile View */
    #nav_menu_views {
        display: none;
    }

    /* Hides "Search" Input Box in Mobile View */
    .nav_menu .item.search {
        display: none;
    }

    /* Hides the Dropdown Menu Button next to the "Mark all read" Button in Mobile View */
    #mark-read-menu .dropdown {
        display: none;
    }
}
```

## User JS

It gives ability to create user-specific JS.

# Users

> **TODO**

## Authentication methods

### HTTP Authentication (Apache)

1. User control is based on the `.htaccess` file.
2. It is best practice to place the `.htaccess` file in the `./i/` subdirectory so the API and other third party services can work.
3. If you want to limit all access to registered users only, place the file in the FreshRSS directory itself or in a parent directory. Note that [WebSub](WebSub.md) and API will not work!
4. Example `.htaccess` file for a user "marie":

```apache
AuthUserFile /home/marie/repertoire/.htpasswd
AuthGroupFile /dev/null
AuthName "Chez Marie"
AuthType Basic
Require user marie
```

More information can be found in the [Apache documentation](http://httpd.apache.org/docs/trunk/howto/auth.html#gettingitworking).

This page assumes you have completed the [server setup](../admins/03_Installation.md).

# Mobile Access

You can access FreshRSS on mobile devices via browser and via mobile apps.


## Access via Browser

The FreshRSS user interface is optimized for both small and large screens. The content will fit nicely on small mobile device screens as well.


## Access via Mobile App

FreshRSS supports access from mobile / native apps for Linux, Android, iOS, Windows and macOS, via two distinct APIs: Google Reader API (best), and Fever API (limited features and less efficient).

A list of known apps is available on the [FreshRSS GitHub page](https://github.com/FreshRSS/FreshRSS#apis--native-apps).


### Enable the API in FreshRSS

1. Under the section “Authentication”, enable the option “Allow API access (required for mobile apps)”.
2. Under the section “Profile”, fill-in the field “API password (e.g., for mobile apps)”.
	* Every user must define an API password.
	* The reason for an API-specific password is that it may be used in less safe situations than the main password, and does not grant access to as many things.

See the [page about the Google Reader compatible API](../developers/06_GoogleReader_API.md) for more details.
See the [page about the Fever compatible API](../developers/06_Fever_API.md) for more details.


### Testing

1. Under the section “Profile”, click on the link like `https://rss.example.net/api/` next to the field “API password”.
2. Click on first link “Check full server configuration”:
	* If you get *PASS* then you are done; all is well.
	* If you get *Bad Request!* or *Not Found*, then your server probably does not accept slashes `/` that are escaped `%2F`, see the next section "Fix server configuration".
	* If you receive any other error message, see the next section “Fix server configuration”.

### Fix server configuration

* Click on the second link “Check partial server configuration (without `%2F` support)”:
	* If you get `PASS`, then the problem is indeed that your server does not accept slashes `/` that are escaped `%2F`.
		* With Apache, remember the directive [`AllowEncodedSlashes On`](http://httpd.apache.org/docs/trunk/mod/core.html#allowencodedslashes)
		* Or use a client that does not escape slashes (such as EasyRSS) ([`check client list`](https://github.com/FreshRSS/FreshRSS#apis--native-apps)).
	* If you get *Service Unavailable!*, then check the preceding section “Enable the API in FreshRSS” again.
	* With __Apache__:
		* If you get *FAIL getallheaders!*, the combination of your PHP version and your Web server does not provide access to [`getallheaders`](http://php.net/getallheaders)
			* Turn on Apache `mod_setenvif` (often enabled by default), or `mod_rewrite` with the following procedure:
				* Allow [`FileInfo` in `.htaccess`](http://httpd.apache.org/docs/trunk/mod/core.html#allowoverride): see the [server setup](../admins/03_Installation.md) again.
				* Enable [`mod_rewrite`](http://httpd.apache.org/docs/trunk/mod/mod_rewrite.html):
					* With Debian / Ubuntu: `sudo a2enmod rewrite`
	* With __nginx__:
		* If you get *Bad Request!*, check your server `PATH_INFO` configuration.
		* If you get *File not found!*, check your server `fastcgi_split_path_info`.
	* If you get *FAIL 64-bit or GMP extension!*, then your PHP version does not pass the requirement of being 64-bit and/or have PHP [GMP](http://php.net/gmp) extension.
		* The easiest is to add the GMP extension. On Debian / Ubuntu: `sudo apt install php-gmp`
	* Update and try again from the preceding section “Testing”.

We may not have answered all of your questions in the previous sections. The FAQ contains some questions that have not been answered elsewhere.

## What is `/i` at the end of the application URL?

Of course, ```/i``` has a purpose! It’s used for performance and usability:

* It allows for serving icons, images, styles and scripts without cookies. Without that trick, those files would be downloaded more often, especially when form authentication is used. Also, HTTP requests would be heavier.
* The ```./p/``` public root can be served without any HTTP access restrictions. Whereas it could be implemented in ```./p/i/```.
* It avoids problems while serving public resources like ```favicon.ico```, ```robots.txt```, etc.
* It allows the logo to be displayed instead of a white page while hitting a restriction or a delay during the loading process.

## Why is `robots.txt` located in a sub-folder?

To increase security, FreshRSS is hosted in two sections. The first section is public (the `./p` folder) and the second section is private (everything else). Therefore the `robots.txt` file is located in the `./p` sub-folder.

As explained in the [security section](../admins/09_AccessControl.html), it’s highly recommended to make only the public section available at the domain level.
With that configuration, `./p` is the root folder for <https://demo.freshrss.org/>, thus making `robots.txt` available at the root of the application.

The same principle applies to `favicon.ico` and `.htaccess`.

## Why do I have errors while registering a feed?

There can be different origins for that problem.
The feed syntax can be invalid, it can be unrecognized by the SimplePie library, the hosting server can be the root of the problem, or FreshRSS can be buggy.
The first step is to identify what causes the problem.
Here are the steps to follow:

1. __Verify if the feed syntax is valid__ with the [W3C on-line tool](https://validator.w3.org/feed/ "RSS and Atom feed validator"). If it’s not valid, there’s nothing we can do.
1. __Verify SimplePie validation__ with the [SimplePie on-line tool](https://simplepie.org/demo/ "SimplePie official demo"). If it’s not recognized, there’s nothing we can do.
1. __Verify FreshRSS integration__ with the [demo](https://demo.freshrss.org "FreshRSS official demo"). If it’s not working, you need to [create an issue on GitHub](https://github.com/FreshRSS/FreshRSS/issues/new "Create an issue for FreshRSS") so we can have a look at it. If it’s working, there’s probably something fishy with the hosting server.

## How can you change a forgotten password?

Since the [1.10.0](https://github.com/FreshRSS/FreshRSS/releases/tag/1.10.0) release, admins can change user passwords directly from the interface. This interface is available under  ```Administration → Manage users```.
Select a user, enter a password, and validate.

Since the [1.8.0](https://github.com/FreshRSS/FreshRSS/releases/tag/1.8.0) release, admins can change user passwords using a terminal. It worth mentioning that you must have access to PHP CLI. Open a terminal, and type the following command:

```sh
./cli/update_user.php --user <username> --password <password>
```

For more information on that matter, please refer to the [dedicated documentation](https://github.com/FreshRSS/FreshRSS/blob/edge/cli/README.md).

## Permissions under SELinux

Some Linux distribution, like Fedora or RedHat Enterprise Linux, have SELinux enabled. This acts similar to a firewall application, so that applications can’t write or modify files under certain conditions. While installing FreshRSS, step 2 can fail if the httpd process can’t write to some data sub-directories. The following command should be executed as root to fix this problem:

```sh
semanage fcontext -a -t httpd_sys_rw_content_t '/usr/share/FreshRSS/data(/.*)?'
restorecon -Rv /usr/share/FreshRSS/data
```

## Why do I have a blank page while trying to configure the sharing options?

The `sharing` word in the URL is a trigger word for some ad-blocker rules. Starting with version 1.16, `sharing` has been replaced by `integration` in the faulty URL while keeping the exact same wording throughout the application.

If you are using a version prior to 1.16, you can disable your ad-blocker for FreshRSS or you can add a rule to allow the `sharing` page to be accessed.

Examples with _uBlock_:

* Whitelist your FreshRSS instance by adding it in _uBlock > Open the dashboard > Whitelist_.
* Authorize your FreshRSS instance to call `sharing` configuration page by adding the rule `*sharing,domain=~yourdomain.com` in _uBlock > Open the dashboard > My filters_

## Problems with firewalls

If you have the error "Blast! This feed has encountered a problem. Please verify that it is always reachable then update it.", it might be because of a firewall misconfiguration.

To identify the problem, here are the steps to follow:

* step 1: Try to reach the feed locally to discard a problem with the feed itself. You can use your browser to this purpose.
* step 2: Try to reach the feed from the host in which FreshRSS is installed. Something like `time curl -v 'https://github.com/FreshRSS/FreshRSS/commits/edge.atom'` should make the deal. If you are running FreshRSS within a Docker container, then you can check connectivity from within the container itself with something similar to `sudo docker exec freshrss php -r "readfile('https://github.com/FreshRSS/FreshRSS/commits/edge.atom');"`. If none of this works, then it might be a problem with your firewall.

Then to fix it, you need to do check your firewall configuration and ensure that you are not blocking connections to IPs and/or ports in which your feeds are located. If using iptables and you are blocking inbound connections to ports 80/443, check that the rules are properly configured and you are not also blocking outbound connections to the very same ports.

For example, when using the firewall provided by Synology, you can block traffic for certain applications (i.e., ports). One could think that these rules would be applied only to incoming connections but specifying * for the originating host of the requests will also include your local networks. To deal with this issue, you will have to add exceptions for your local networks to be able to access those ports with a higher priority than the one blocking incoming connections. This could be similar for other frontends to iptables. Please check the following discussion about a [similar issue](https://www.reddit.com/r/synology/comments/8fo2sj/ds918_firewall_blocking_outgoing_traffic_from/).

# Sharing Services

FreshRSS has the option to share links with a bunch of services.

## Available Services: Simple Sharing

| Service       | Short description                                      | Notes                                                         |
|:--------------|:-------------------------------------------------------|:--------------------------------------------------------------|
| Clipboard     | Copy article link into the operation system clipboard | |
| Email         | Open the email app to send the article link            | |
| Print         | Open browser’s print dialog to print out the article   | |

## Available Services: Hosted Services

| Service           | Short description                                    | Links                                            | Notes                                                         |
|:------------------|:-----------------------------------------------------|:-------------------------------------------------|:--------------------------------------------------------------|
| Buffer         | Buffer.com is a social media management platform for scheduling, publishing, and analyzing content. | [Website](https://buffer.com) ||
| Diaspora*         | The online social world where you are in control     | [Website](https://diasporafoundation.org/), [Wikipedia](https://en.wikipedia.org/wiki/Diaspora_(social_network)) |  |
| Facebook          | Worldwide social network (by Meta Platforms)         | [Website](https://facebook.com), [Wikipedia](https://en.wikipedia.org/wiki/Facebook) | |
| GNU social        | Social communication software for both public and private communications | [Website](https://gnu.io/social/) | |
| Journal du hacker | Le Journal du hacker s'inspire directement du site anglophone Hacker News | [Website](https://www.journalduhacker.net/) | |
| Known based sites | Its robust open source framework can be used to build fully-fledged community sites, or a blog for a single user. | [Website](https://withknown.com/) | |
| Lemmy             | Selfhosted social link aggregation and discussion platform | [Website](https://join-lemmy.org/) | |
| Linkding          | Selfhosted bookmark service | [Website](https://github.com/sissbruecker/linkding) | |
| LinkedIn          | Business and employment-oriented online service      | [Website](https://www.linkedin.com/), [Wikipedia](https://en.wikipedia.org/wiki/LinkedIn)| |
| Mastodon          | Self-hosted social networking & microblogging services | [Website](https://joinmastodon.org/), [Wikipedia](https://en.wikipedia.org/wiki/Mastodon_(software)) | |
| Movim             | A powerful web frontend for XMPP                     | [Website](https://movim.eu/) | |
| Omnivore          | A complete, open source read-it-later solution for people who love to read. | [Website](https://omnivore.app/) | |
| Pinboard          | Social Bookmarking for Introverts                    | [Website](https://pinboard.in/) | |
| Pinterest         | Is an image sharing and social media service designed to enable saving and discovery of information| [Website](https://pinterest.com/), [Wikipedia](https://en.wikipedia.org/wiki/Pinterest) | |
| Pocket            | Social bookmarking (previous "Read it Later", owned by Mozilla) | [Website](https://getpocket.com), [Wikipedia](https://en.wikipedia.org/wiki/Pocket_(service)) | |
| Raindrop.io       | All-in-one bookmark manager                          | [Website](https://raindrop.io/)| |
| Reddit            | A network of communities where people can dive into their interests, hobbies and passions| [Website](https://www.reddit.com/), [Wikipedia](https://en.wikipedia.org/wiki/Reddit)| |
| Shaarli           | Self-hosted minimalist bookmark manager and link sharing service | [Website](https://shaarli.readthedocs.io/) | |
| Twitter           | Microblogging social network                         | [Website](https://twitter.com), [Wikipedia](https://de.wikipedia.org/wiki/Twitter) | |
| wallabag          | Save and classify articles. Read them later. Freely  | [Website](https://www.wallabag.org) | Compatible to version 1 and 2 |
| Whatsapp          | Instant messaging and voice-over-IP service owned by Meta Platforms| [Website](https://www.whatsapp.com), [Wikipedia](https://en.wikipedia.org/wiki/WhatsApp) | |
| XING              | Career-oriented social networking site, operated by New Work SE | [Website](https://www.xing.com/), [Wikipedia](https://en.wikipedia.org/wiki/XING) | |

## Configuration

Select the needed sharing services in the configuration menu (Configuration / Sharing).

## Usage

Activate the sharing menu in configuration menu (Configuration / Display). It is only available for the bottom line.

The menu with the selected services is available in the footer of article.

## Add More Sharing Services

Please open a new issue on [GitHub](https://github.com/FreshRSS/FreshRSS/issues) and support us with information.

# Refreshing feeds

To take full advantage of FreshRSS, it needs to retrieve new items from the feeds you have subscribed to. There are several ways to do this:

- [Manual update](#manual-update)
    - [Complete update](#complete-update)
    - [Partial update](#partial-update)
- [Automatic update with cron](#automatic-update-with-cron)
- [Online cron](#online-cron)
    - [For Form Authentication](#for-form-authentication)
    - [For HTTP authentication](#for-http-authentication)
    - [For No authentication None](#for-no-authentication-none)
- [Feed configuration of “Do not automatically refresh more often than”](#feed-configuration-of-do-not-automatically-refresh-more-often-than)
    - [Background](#background)
    - [Default value](#default-value)
    - [Individual feed configuration](#individual-feed-configuration)

## Manual update

If you can’t or don’t want to use the automatic method, you can update manually. There are two methods for updating all or some of the feeds.

### Complete update

This update occurs on all feeds. To trigger it, simply click on the update link in the navigation menu.

![Navigation menu](../img/users/refresh.1.png)

When the update starts, a progress bar appears and changes while feeds are processed.

![Progress bar](../img/users/refresh.5.png)

### Partial update

This update occurs on the selected feed only. To trigger it, simply click on the update link in the feed menu.

![Feed menu](../img/users/refresh.2.png)

## Automatic update with cron

This is the recommended method.

This method is only available if you have access to the scheduled tasks of the machine on which your FreshRSS instance is installed.

The script is named *actualize_script.php* and is located in the *app* folder. The scheduled task syntax will not be explained here. However, here is [a quick introduction to crontab](http://www.adminschoice.com/crontab-quick-reference/) that might help you.

Here is an example to trigger article update every hour.

```cron
0 * * * * php /path/to/FreshRSS/app/actualize_script.php > /tmp/FreshRSS.log 2>&1
```

## Online cron

If you do not have access to the installation server scheduled task, you can still automate the update process.

To do so, you need to create a scheduled task, which need to call a specific URL:
<https://freshrss.example.net/i/?c=feed&a=actualize> (it could be different depending on your installation). Depending on your application authentication method, you need to adapt the scheduled task.

Special parameters to configure the script - all parameters can be combined:

- Parameter `ajax`
<https://freshrss.example.net/i/?c=feed&a=actualize&ajax=1>
Only a status site is returned and not a complete website. Example: "OK"

- Parameter `maxFeeds`
<https://freshrss.example.net/i/?c=feed&a=actualize&maxFeeds=30>
If *maxFeeds* is set the configured amount of feeds is refreshed at once. The default setting is `10`.

- Parameter `token`
<https://freshrss.example.net/i/?c=feed&a=actualize&token=542345872345734>
Security parameter to prevent unauthorized refreshes. For detailed Documentation see "Form authentication".

### For Form Authentication

If your FreshRSS instance is using Form Authentication, you can configure an authentication token to grant access to the online cron.

![Token configuration](../img/users/token.1.png)

You can target a specific user by adding their username to the query string, with `&user=insert-username`:

The scheduled task syntax should look as follows:

<https://freshrss.example.net/i/?c=feed&a=actualize&maxFeeds=10&ajax=1&user=someone&token=my-token>

Alternatively, but not recommended, if you configure the application to allow anonymous reading, you can also allow anonymous users to update feeds (“Allow anonymous refresh of the articles”), and that does not require a token.

![Anonymous access configuration](../img/users/anonymous_access.1.png)

### For HTTP authentication

If your FreshRSS instance is using HTTP authentication, you’ll need to provide your credentials to the scheduled task.

**Note:** This method is discouraged as your credentials are stored in plain text.

```cron
0 * * * * curl -u alice:password123 'https://freshrss.example.net/i/?c=feed&a=actualize&maxFeeds=10&ajax=1&user=alice'
```

On some systems, that syntax might also work:

<https://alice:password123@freshrss.example.net/i/?c=feed&a=actualize&maxFeeds=10&ajax=1&user=alice>

### For No authentication (None)

If your FreshRSS instance uses no authentication (public instance, default user):

<https://freshrss.example.net/i/?c=feed&a=actualize&maxFeeds=10&ajax=1>

## Feed configuration of “Do not automatically refresh more often than”

### Background

FreshRSS does not, by design, supports pull refreshes at frequencies higher than once every 15 minutes. But FreshRSS supports [instant push (WebSub)](WebSub.md).

FreshRSS is part of an RSS ecosystem. A typical reaction that we have seen from several servers is to simply ban by, IP, user-agent, or to remove their RSS feed altogether. Bad user behaviours affect the larger community.

### Default value

The default value of “Do not automatically refresh more often than” is set in Configuration -> Archiving.

The lowest global/default purposely cannot be set faster than every 20 minutes, to avoid wasting resources and make sure the RSS ecosystem remains sane.

### Individual feed configuration

Under the settings for individual feeds, you can go down to 15min.

---
Read more:
- [Normal, Global and Reader view](./03_Main_view.md)
- [Filter the feeds and search](./10_filter.md)

# Filtering articles

## Purpose

When the number of articles stored by FreshRSS inevitably grows larger, it’s important to use efficient filters to display only a subset of the articles. There are several methods that filter with different criteria. Usually those methods can be combined.

## By category

This is the easiest method. You only need to click on the category title in the side panel. There are two special categories at the top of the panel:

* *Main feed* displays only articles from feeds marked as available in that category
* *Favourites* displays only articles marked as favourites

## By feed

There are several methods to filter articles by feed:

* by clicking the feed title in the side panel
* by clicking the feed title in the article details
* by filtering in the feed options from the side panel
* by filtering in the feed configuration

![Feed filter](../img/users/feed.filter.1.png)

## By status

Each article has two attributes that can be combined. The first attribute indicates whether or not the article has been read. The second attribute indicates if the article was marked as favorite or not.

In version 0.7, attribute filters are available in the article display dropdown list. With this version, it’s not possible to combine filters. For instance, it’s not possible to display only read and favorite articles.

![Attribute filters in 0.7](../img/users/status.filter.0.7.png)

Starting with version 0.8, all attribute filters are visible as toggle icons. They can be combined. As any combination is possible, some have the same result. For instance, the result for all filters selected is the same as no filter selected.

![Attribute filters in 0.8](../img/users/status.filter.0.8.png)

By default, this filter displays only unread articles

## By content

It is possible to filter articles by their content by inputting a string in the search field.

## With the search field

You can use the search field to further refine results:

* by feed ID: `f:123` or multiple feed IDs (*or*): `f:123,234,345`
* by author: `author:name` or `author:'composed name'`
* by title: `intitle:keyword` or `intitle:'composed keyword'`
* by URL: `inurl:keyword` or `inurl:'composed keyword'`
* by tag: `#tag` or `#tag+with+whitespace`
* by free-text: `keyword` or `'composed keyword'`
* by date of discovery, using the [ISO 8601 time interval format](http://en.wikipedia.org/wiki/ISO_8601#Time_intervals): `date:<date-interval>`
	* From a specific day, or month, or year:
		* `date:2014-03-30`
		* `date:2014-03` or `date:201403`
		* `date:2014`
	* From a specific time of a given day:
		* `date:2014-05-30T13`
		* `date:2014-05-30T13:30`
	* Between two given dates:
		* `date:2014-02/2014-04`
		* `date:2014-02--2014-04`
		* `date:2014-02/04`
		* `date:2014-02-03/05`
		* `date:2014-02-03T22:00/22:15`
		* `date:2014-02-03T22:00/15`
	* After a given date:
		* `date:2014-03/`
	* Before a given date:
		* `date:/2014-03`
	* For a specific duration after a given date:
		* `date:2014-03/P1W`
	* For a specific duration before a given date:
		* `date:P1W/2014-05-25T23:59:59`
	* For the past duration before now (the trailing slash is optional):
		* `date:P1Y/` or `date:P1Y` (past year)
		* `date:P2M/` (past two months)
		* `date:P3W/` (past three weeks)
		* `date:P4D/` (past four days)
		* `date:PT5H/` (past five hours)
		* `date:PT30M/` (past thirty minutes)
		* `date:PT90S/` (past ninety seconds)
		* `date:P1DT1H/` (past one day and one hour)
* by date of publication, using the same format: `pubdate:<date-interval>`
* by custom label ID `L:12` or multiple label IDs: `L:12,13,14` or with any label: `L:*`
* by custom label name `label:label`, `label:"my label"` or any label name from a list (*or*): `labels:"my label,my other label"`
* by several label names (*and*): `label:"my label" label:"my other label"`
* by entry (article) ID: `e:1639310674957894` or multiple entry IDs  (*or*): `e:1639310674957894,1639310674957893`
* by user query (saved search) name: `search:myQuery`, `search:"My query"` or saved search ID: `S:3`
	* internally, those references are replaced by the corresponding user query in the search expression

Be careful not to enter a space between the operator and the search value.

Some operators can be used negatively, to exclude articles, with the same syntax as above, but prefixed by a `!` or `-`:
`!f:234`, `-author:name`, `-intitle:keyword`, `-inurl:keyword`, `-#tag`, `!keyword`, `!date:2019`, `!date:P1W`, `!pubdate:P3d/`.

It is also possible to combine keywords to create a more precise filter.
For example, you can enter multiple instances of `f:`, `author:`, `intitle:`, `inurl:`, `#`, and free-text.

Combining several search criteria implies a logical *and*, but the keyword ` OR `
can be used to combine several search criteria with a logical *or* instead: `author:Dupont OR author:Dupond`

You don’t have to do anything special to combine multiple negative operators. Writing `!intitle:'thing1' !intitle:'thing2'` implies AND, see above. For more pointers on how AND and OR interact with negation, see [this GitHub comment](https://github.com/FreshRSS/FreshRSS/issues/3236#issuecomment-891219460).
Additional reading: [De Morgan’s laws](https://en.wikipedia.org/wiki/De_Morgan%27s_laws).

Finally, parentheses may be used to express more complex queries, with basic negation support:

* `(author:Alice OR intitle:hello) (author:Bob OR intitle:world)`
* `(author:Alice intitle:hello) OR (author:Bob intitle:world)`
* `!((author:Alice intitle:hello) OR (author:Bob intitle:world))`
* `(author:Alice intitle:hello) !(author:Bob intitle:world)`
* `!(S:1 OR S:2)`

> ℹ️ If you need to search for a parenthesis, it needs to be escaped like `\(` or `\)`

## By sorting by date

You can change the sort order by clicking the toggle button available in the header.

## Bookmark the current query

Once you came up with your perfect filter, it would be a shame if you had to recreate it every time you need to use it.

Luckily, there is a way to bookmark them for later use.
We call them [*user queries*](./user_queries.md).
You can create as many as you want, the only limit is how they will be displayed on your screen.

Read more about [*user queries*](./user_queries.md) to learn how to create them, use them, and even reshare them via HTML / RSS / OPML.

---
Read more:
* [Normal, Global and Reader view](./03_Main_view.md)
* [Refreshing the feeds](./09_refreshing_feeds.md)
* [User queries](./user_queries.md)

# Website scraping

FreshRSS has a built-in [Web scraping](https://en.wikipedia.org/wiki/Web_scraping) engine that generates a feed from websites that have no RSS/Atom feed published.

## How to add

Go to “Subscription Management” where a new feed can be added.
Change the “Type of feed source” to one of:
- “HTML + XPath (Web scraping)”
- JSON Feed (see [`jsonfeed.org`](https://www.jsonfeed.org/))
- JSON (Dotted paths)

An additional list of text boxes to configure the Web scraping will show.

For HTML + XPath, [XPath 1.0](https://www.w3.org/TR/xpath-10/) is used as traversing language.

### Get the XPath path

Firefox: the built-in “inspect” tool may be used to help create a valid XPath expression.
Select the node in the HTML, right click with your mouse and chose “Copy” and “XPath”.
The XPath is stored in your clipboard now.

### Get the JSON dotted path

Suppose the JSON to which you are subscribing to (or scraping) looks like this:

```json
{
	"data": {
		"items": [
			{
				"meta": {"title": "Some news item"},
				"content": "Content of the news",
				"links": ["https://example.net/1", "https://example.org/1"]
			},
			{
				"meta": {"title": "Some other news item"},
				"content": "Yet more content",
				"links": ["https://example.net/2", "https://example.org/2"]
			}
		]
	}
}
```

The *dot notation* and *bracket notation* (only numeric) are supported.

Then the items are under `data.items`, and within each item, the title is `meta.title`,
and the link would be `links[1]`.

It is a similar syntax to the JavaScript way to access JSON: `object.object.array[2].property`.

## Tips & tricks

- [Timezone of date](https://github.com/FreshRSS/FreshRSS/discussions/5483)

## Recommended external manuals

- [XPath Scraping with FreshRSS, by Dan Q](https://danq.me/2022/09/27/freshrss-xpath/) (September 2022)

# The WebSub protocol

[WebSub](https://www.w3.org/TR/websub/) (formerly [PubSubHubbub](https://github.com/pubsubhubbub/PubSubHubbub)) is a standard protocol
to instantly receive (push) notifications when some new content is available on a remote server,
for instance when a new article is available via RSS / ATOM.

FreshRSS supports WebSub natively.
Just like for the FreshRSS API to work from a mobile phone, supporting WebSub requires that your FreshRSS instance is routable (that is to say, with a public IP, that can be accessed from third-party servers).

## WebSub terminology

There are tree main concepts:

* **publisher**: Web site publishing content such as RSS / ATOM feeds;
* **subscriber**: Feed aggregator such as FreshRSS;
* **hub**: Intermediate technical component in charge of notifying all subscribers instantly when a publisher has some new content.
The same hub can serve several publishers and their subscribers.
Some publishers have a built-in hub.

## Enabling WebSub in FreshRSS

FreshRSS supports WebSub natively, but requires a public address (read from the `base_url` configuration),
and requires the `./FreshRSS/p/api/` folder to be publicly accessible (just like for other FreshRSS APIs).

During the initial Web-based setup, support for WebSub is enabled if the server hosting FreshRSS appears to have a public address.
In any case, check your `./data/config.php` for:

```php
'base_url' => 'https://freshrss.example.net/',
'pubsubhubbub_enabled' => true,
```

Additional logs about WebSub are available in `./FreshRSS/data/users/_/log_pshb.txt`

## Test WebSub compatibility of your FreshRSS instance

You can test that WebSub works properly in your FreshRSS instance with a service such as:

* <http://push-tester.cweiske.de>

When you create a new article, it should instantly be available in your FreshRSS instance.

## Examples of feeds using WebSub

Many individual feeds and platforms already offer instant notifications through WebSub, such as:
[Friendica instances](https://friendi.ca), WordPress (from WordPress.com or with [an extension](https://wordpress.org/plugins/pubsubhubbub/)), Blogger sites, Medium sites, etc.

## Test WebSub compatibility of an RSS / ATOM feed

* <https://test.livewire.io> (for any feed)
* <https://websub.rocks/publisher> (for feeds you control)

## Add WebSub to your RSS / ATOM feeds

Your CMS (e.g. WordPress) might already offer WebSub as an option, such as:

* <https://wordpress.org/plugins/pushpress/>

Otherwise, you can make a solution that notifies a hub, such as:

* <https://websubhub.com>
* <https://pubsubhubbub.appspot.com>

Or even deploy your own hub, such as:

* <https://github.com/flusio/Webubbub>

## Test WebSub compatibility of a hub

* <https://websub.rocks/hub/100>

# User queries

*User queries* are a way to store any FreshRSS search query.

Read about [the filters](./10_filter.md) to learn the different ways to search and filter
articles in FreshRSS.

## Bookmark the current query

Once you have a search query with a filter, it can be saved.

To do so, display the user queries drop-down menu by clicking the button next to the state buttons:

![User queries drop-down](../img/users/user.queries.drop-down.empty.png)

Then click on the bookmark action.

## Using a bookmarked query

Display the user queries drop-down menu by clicking the button next to the state buttons:

![User queries drop-down](../img/users/user.queries.drop-down.not.empty.png)

Then click on the bookmarked query, the previously stored query will be applied.

> ℹ️ Note that only the search query is stored, not the articles.
> So the results you are seeing one day might be different another day.

## Share your user queries

A prerequisite is that the FreshRSS API(s) must be enabled in FreshRSS authentication settings.

From the configuration page of the user queries,
it is possible to share the output of the user queries with external users,
in the formats HTML, RSS, and OPML:

![Share user query](../img/users/user-query-share.png)

> ℹ️ Note that the sharing as OPML is only available for user queries based on all feeds, a category, or a feed.
> Sharing by OPML is **not** available for queries based on user labels or favourites or important feeds,
> to avoid leaking some feed details in an unintended manner.

### Additional parameters for shared user queries

Some parameters can be manually added to the URL:

* `f`: Format of output. Can be `html`, `rss` (`atom` is an alias), or `opml`.
* `hours`: Show only the articles newer than this number of hours.
* `nb`: Number of articles to return. Limited by `max_posts_per_rss` in the user configuration. Can be used in combination with `offset` for pagination.
* `offset`: Skip a number of articles. Used in particular by the HTML view for pagination.
* `order`: Show the newest articles at the top with `DESC`, or the oldest articles at the top with `ASC`. By default, will use the sort order defined by the user query.

## Sharing with a master token (deprecated)

Before FreshRSS 1.24, the only option to reshare an RSS output was by using a master token,
like `https://freshrss.example.net/?a=rss&user=alice&token=abc123`

This was mostly intended for sharing between systems controlled by the same user, and not for sharing publicly.

This method **is not advised anymore** as it is not safe to use the same master token for multiple outputs,
especially not when shared with other persons.

Now, sharing RSS outputs via user queries is the recommended approach for all scenarios.