Difference between revisions of "Webserver"

From Official Kodi Wiki
Jump to navigation Jump to search
>Montellese
(webserver description)
 
(→‎Hints: Fix up the formatting of the example Apache config.)
 
(23 intermediate revisions by 6 users not shown)
Line 1: Line 1:
XBMC comes with a builtin webserver based on [http://www.gnu.org/software/libmicrohttpd/ libmicrohttpd] which provides several services accessible through [http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP].
<section begin="intro" />{{kodi}} comes with a builtin webserver based on [http://www.gnu.org/software/libmicrohttpd/ libmicrohttpd] which provides several services accessible through [http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP].<section end="intro" />


==Enabling the webserver==
== Enabling the webserver ==
The webserver is disabled by default and has to be manually enabled by the user. This can be done in [[Settings]] > [[Settings/Services]] > Allow control of XBMC via HTTP. The settings allow to specify a custom port number and an optional username and password for HTTP's [http://en.wikipedia.org/wiki/Basic_access_authentication Basic Access Authentication]. Furthermore a [[Web interface]] can be chosen which will be used when accessing the webserver without any specific path.
The webserver is disabled by default and has to be manually enabled by the user. This can be done in {{highlight|bordered=yes|[[Settings/Services#Webserver|Settings Services → Webserver → Allow control of {{Kodi}} via HTTP]]}}. The settings allow to specify a custom port number and an optional username and password for HTTP's [http://en.wikipedia.org/wiki/Basic_access_authentication Basic Access Authentication]. Furthermore a [[Web interface]] can be chosen which will be used when accessing the webserver without any specific path.


===Hints===
=== Hints ===
*If the webserver fails to start make sure you use a port that is not blocked by your firewall and is not used by any other process running on the same machine. If there is another webserver like Apache running on the same machine it is very likely that port 80 (HTTP default port) is already used.
* If the webserver fails to start make sure you use a port that is not blocked by your firewall and is not used by any other process running on the same machine. If there is another webserver like Apache running on the same machine it is very likely that port 80 (HTTP default port) is already used.
*On Linux ports below 1024 require super-user privileges and are therefore not available to XBMC.
* On Linux, ports below 1024 require super-user privileges and are therefore not available to {{kodi}}. For Linux, you must change the port number to a port number above 1024 that's not in use on your computer, like 1485, 1588 or 1066 for example.  Those 3 port numbers have no popular uses registered with IANA, the Internet Assigned Numbers Authority.  Remote control via HTTP will see the web server with whatever port you choose.
* For use in a virtual hosts environment in Apache, the following directives can be used:


==Services==
<syntaxhighlight lang="apache">
# Kodi configuration
# Replace kodiserver with actual names.
 
ServerName kodiserver
DocumentRoot /
LogLevel emerg
ErrorLog /var/log/apache2/kodiserver_error.log
CustomLog /var/log/apache2/kodiserver_access.log "vhost_combined"
ProxyPass / http://kodiserver:8080/ nocanon
ProxyPassReverse / http://kodiserver:8080/
<Directory "/">
  allow from all
  Options +Indexes
</Directory>
AllowEncodedSlashes On
</syntaxhighlight>
 
AllowEncodedSlashes is necessary to have webpages work properly.
 
nocanon is used to disable url encoding use this if images are not showing in the webbrowser.
 
== Services ==
The webserver offers several services which can be accessed based on the path specified in the HTTP request. The webserver is accessible through HTTP using the following URL
The webserver offers several services which can be accessed based on the path specified in the HTTP request. The webserver is accessible through HTTP using the following URL
<pre>http://<your ip>:<configured port>/</pre>
<pre>http://<your ip>:<configured port>/</pre>


===Webinterface===
=== Webinterface ===
When no path is specified or the specified path does not correspond to any of the available services the webserver will try to locate the requested path/file in the configured [[Web interface]].
When no path is specified or the specified path does not correspond to any of the available services the webserver will try to locate the requested path/file in the configured [[Web interface]].


===Webinterface addons /addons===
=== Webinterface addons /addons ===
Requesting the /addons path will show a HTML page with a list of all installed and available [[:Category:Web interface add-ons|webinterface addons]]. By appending the identifier of one of the webinterface addons to the /addons path it is possible to access all the available webinterfaces without configuring them in the settings.
Requesting the /addons path will show a HTML page with a list of all installed and available webinterface addons. By appending the identifier of one of the webinterface addons to the /addons path it is possible to access all the available webinterfaces without configuring them in the settings.


===Image cache /image===
=== Image cache /image ===
The image cache service provides access to cached images (thumbnails, fanart, ...) of media items. The image URL (image://) returned by JSON-RPC has to be URL encoded before appending it:
The image cache service provides access to cached images (thumbnails, fanart, ...) of media items. The image URL (image://) returned by JSON-RPC has to be URL encoded before appending it:
<pre>http://<your ip>:<configured port>/image/<url encoded image:// path></pre>
<pre>http://<your ip>:<configured port>/image/<url encoded image:// path></pre>


===JSON-RPC API /jsonrpc===
=== JSON-RPC API /jsonrpc ===
The JSON-RPC API service provides access to the [[JSON-RPC API]] using [http://en.wikipedia.org/wiki/POST_(HTTP) HTTP POST] or GET. Requesting the /jsonrpc path without any additional POST or GET data will return the full [[JSON-RPC_API#Documentation|documentation]] of the JSON-RPC API in JSON schema format.
The JSON-RPC API service provides access to the [[JSON-RPC API]] using [http://en.wikipedia.org/wiki/POST_(HTTP) HTTP POST] or GET. Requesting the /jsonrpc path without any additional POST or GET data will return the full [[JSON-RPC API#Documentation|documentation]] of the JSON-RPC API in JSON schema format.


===Virtual File System /vfs===
=== Virtual File System /vfs ===
The Virtual File System (VFS) service provides access to files accessible to XBMC through its VFS. The VFS path has to be URL encoded before appending it:
The Virtual File System (VFS) service provides access to files accessible to {{kodi}} through its VFS. The VFS path has to be URL encoded before appending it:
<pre>http://<your ip>:<configured port>/vfs/<url encoded vfs path></pre>
<pre>http://<your ip>:<configured port>/vfs/<url encoded vfs path></pre>


{{Frodo|In an effort to make the Virtual File System service more secure (in Eden and before it allowed access to literally any file on the local hard disc and on network shares accessible to XBMC) the access has been limited to files within directories that have been specified by the user as sources (video, music, files, programs) in XBMC.}}
As of XBMC v12 Frodo, in an effort to make the Virtual File System service more secure (in Eden and before it allowed access to literally any file on the local hard disc and on network shares accessible to {{kodi}}) the access has been limited to files within directories that have been specified by the user as sources (video, music, files, programs) in {{kodi}}.
 
 


==See also==
{{Updated|16}}
*[[JSON-RPC API]]
*[[Web Server HTTP API]] - Depreciated since XBMC v10, removed since XBMC v12
*[[Web interface]]
*[[Add-on:Default web interface]]
*[[:Category:Web interface add-ons]]
*[[:Category:Standalone web interfaces]]

Latest revision as of 22:29, 27 January 2022

Kodi comes with a builtin webserver based on libmicrohttpd which provides several services accessible through HTTP.

1 Enabling the webserver

The webserver is disabled by default and has to be manually enabled by the user. This can be done in Settings → Services → Webserver → Allow control of Kodi via HTTP. The settings allow to specify a custom port number and an optional username and password for HTTP's Basic Access Authentication. Furthermore a Web interface can be chosen which will be used when accessing the webserver without any specific path.

1.1 Hints

  • If the webserver fails to start make sure you use a port that is not blocked by your firewall and is not used by any other process running on the same machine. If there is another webserver like Apache running on the same machine it is very likely that port 80 (HTTP default port) is already used.
  • On Linux, ports below 1024 require super-user privileges and are therefore not available to Kodi. For Linux, you must change the port number to a port number above 1024 that's not in use on your computer, like 1485, 1588 or 1066 for example. Those 3 port numbers have no popular uses registered with IANA, the Internet Assigned Numbers Authority. Remote control via HTTP will see the web server with whatever port you choose.
  • For use in a virtual hosts environment in Apache, the following directives can be used:
# Kodi configuration
# Replace kodiserver with actual names.

ServerName kodiserver
DocumentRoot /
LogLevel emerg
ErrorLog /var/log/apache2/kodiserver_error.log
CustomLog /var/log/apache2/kodiserver_access.log "vhost_combined"
ProxyPass / http://kodiserver:8080/ nocanon
ProxyPassReverse / http://kodiserver:8080/
<Directory "/">
  allow from all
  Options +Indexes
</Directory>
AllowEncodedSlashes On

AllowEncodedSlashes is necessary to have webpages work properly.

nocanon is used to disable url encoding use this if images are not showing in the webbrowser.

2 Services

The webserver offers several services which can be accessed based on the path specified in the HTTP request. The webserver is accessible through HTTP using the following URL

http://<your ip>:<configured port>/

2.1 Webinterface

When no path is specified or the specified path does not correspond to any of the available services the webserver will try to locate the requested path/file in the configured Web interface.

2.2 Webinterface addons /addons

Requesting the /addons path will show a HTML page with a list of all installed and available webinterface addons. By appending the identifier of one of the webinterface addons to the /addons path it is possible to access all the available webinterfaces without configuring them in the settings.

2.3 Image cache /image

The image cache service provides access to cached images (thumbnails, fanart, ...) of media items. The image URL (image://) returned by JSON-RPC has to be URL encoded before appending it:

http://<your ip>:<configured port>/image/<url encoded image:// path>

2.4 JSON-RPC API /jsonrpc

The JSON-RPC API service provides access to the JSON-RPC API using HTTP POST or GET. Requesting the /jsonrpc path without any additional POST or GET data will return the full documentation of the JSON-RPC API in JSON schema format.

2.5 Virtual File System /vfs

The Virtual File System (VFS) service provides access to files accessible to Kodi through its VFS. The VFS path has to be URL encoded before appending it:

http://<your ip>:<configured port>/vfs/<url encoded vfs path>

As of XBMC v12 Frodo, in an effort to make the Virtual File System service more secure (in Eden and before it allowed access to literally any file on the local hard disc and on network shares accessible to Kodi) the access has been limited to files within directories that have been specified by the user as sources (video, music, files, programs) in Kodi.