'\" -*- coding: UTF-8 -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH mapproxy-util-autoconfig 1 "13 April 2023" "" ""
.SH NAME
mapproxy-util-autoconfig \- creates MapProxy and MapProxy-seeding configurations
.SH SYNOPSIS
'nh
.fi
.ad l
\fBmapproxy-util autoconfig\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
[\fIOPTIONS\fR]
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
\fBmapproxy-util autoconfig\fR creates MapProxy and
MapProxy-seeding configurations based on existing WMS capabilities
documents.
.PP
It creates a \*(T<source\*(T> for each available layer.
The source will include a BBOX coverage from the layer extent,
\*(T<legendurl\*(T> for legend graphics,
\*(T<featureinfo\*(T> for querlyable layers,
scale hints and all detected \*(T<supported_srs\*(T>.
It will duplicate the layer tree to the \*(T<layers\*(T>
section of the MapProxy configuration, including the name, title and
abstract.
.PP
The tool will create a cache for each source layer and
\*(T<supported_srs\*(T> if there is a grid configured in your
\*(T<\fB\-\-base\fR\*(T> configuration for that SRS.
.PP
The MapProxy layers will use the caches when available, otherwise they
will use the source directly (cascaded WMS).
.RS 
\fBNote\fR
.PP
The tool can help you to create new configations, but it can\(cqt
predict how you will use the MapProxy services.
The generated configuration can be highly inefficient, especially when
multiple layers with separate caches are requested at once.
Please make sure you understand the configuration and check the
documentation for more options that are useful for your use-cases.
.RE
.SH OPTIONS
.TP 
\*(T<\fB\-\-capabilities\fR\*(T> \fIurl|filename\fR
URL or filename of the WMS capabilities document.
The tool will add \*(T<REQUEST\*(T> and
\*(T<SERVICE\*(T> parameters to the URL as necessary.
.TP 
\*(T<\fB\-\-output\fR\*(T> \fIfilename\fR
Filename for the created MapProxy configuration.
.TP 
\*(T<\fB\-\-output\-seed\fR\*(T> \fIfilename\fR
Filename for the created MapProxy-seeding configuration.
.TP 
\*(T<\fB\-\-force\fR\*(T>
Overwrite any existing configuration with the same output filename.
.TP 
\*(T<\fB\-\-base\fR\*(T> \fIfilename\fR
Base configuration that should be included in the
\*(T<\fB\-\-output\fR\*(T> file with the
\*(T<base\*(T> option.
.TP 
\*(T<\fB\-\-overwrite\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-overwrite\-seed\fR\*(T> \fIfilename\fR
YAML configuration that overwrites configuration options before
the generated configuration is written to
\*(T<\fB\-\-output\fR\*(T>/\*(T<\fB\-\-output\-seed\fR\*(T>.
.SS EXAMPLE
Print configuration on console:
.PP
.nf
\*(T<
\fBmapproxy\-util autoconfig\fR \e
    \fB\-\-capabilities\fR http://osm.omniscale.net/proxy/service
      \*(T>
.fi
.PP
Write MapProxy and MapProxy-seeding configuration to files:
.PP
.nf
\*(T<
\fBmapproxy\-util autoconfig\fR \e
    \fB\-\-capabilities\fR http://osm.omniscale.net/proxy/service \e
    \fB\-\-output\fR mapproxy.yaml \e
    \fB\-\-output\fR\fB\-seed\fR seed.yaml
      \*(T>
.fi
.PP
Write MapProxy configuration with caches for grids from
\*(T<\fIbase.yaml\fR\*(T>:
.PP
.nf
\*(T<
\fBmapproxy\-util autoconfig\fR \e
    \fB\-\-capabilities\fR http://osm.omniscale.net/proxy/service \e
    \fB\-\-output\fR mapproxy.yaml \e
    \fB\-\-base\fR base.yaml
      \*(T>
.fi
.SH OVERWRITES
It's likely that you need to tweak the created configuration - e.g. to
define another coverage, disable featureinfo, etc.
You can do this by editing the output file of course, or you can modify
the output by defining all changes to an overwrite file.
Overwrite files are applied every time you call
\fBmapproxy-util autoconfig\fR.
.PP
Overwrites are YAML files that will be merged with the created
configuration file.
.PP
The overwrites are applied independently for each
\*(T<services\*(T>, \*(T<sources\*(T>,
\*(T<caches\*(T> and \*(T<layers\*(T> section.
That means, for example, that you can modify the
\*(T<supported_srs\*(T> of a source and the tool will use the
updated SRS list to decide which caches will be configured for that
source.
.SS EXAMPLE
Created configuration:
.PP
.nf
\*(T<
sources:
  mysource_wms:
    type: wms
    req:
        url: http://example.org
        layers: a
      \*(T>
.fi
.PP
Overwrite file:
.PP
.nf
\*(T<
sources:
  mysource_wms:
    supported_srs: ['EPSG:4326'] # add new value for mysource_wms
    req:
        layers: a,b  # overwrite existing value
        custom_param: 42  #  new value
      \*(T>
.fi
.PP
Actual configuration written to \*(T<\fB\-\-output\fR\*(T>:
.PP
.nf
\*(T<
sources:
  mysource_wms:
    type: wms
    supported_srs: ['EPSG:4326']
    req:
        url: http://example.org
        layers: a,b
        custom_param: 42
      \*(T>
.fi
.SS "SPECIAL KEYS"
There are a few special keys that you can use in your overwrite file.
.TP 
All
The value of the \*(T<__all__\*(T> key will be merged
into all dictionaries.
The following overwrite will add \*(T<sessionid\*(T> to
the \*(T<req\*(T> options of all
\*(T<sources\*(T>:

.nf
\*(T<
sources:
  __all__:
    req:
      sessionid: 123456789
              \*(T>
.fi
.TP 
Extend
The values of keys ending with \*(T<__extend__\*(T>
will be added to existing lists.

To add another SRS for one source:

.nf
\*(T<
sources:
    my_wms:
      supported_srs__extend__: ['EPSG:31467']
              \*(T>
.fi
.TP 
Wildcard
The values of keys starting or ending with three underscores
(\*(T<___\*(T>) will be merged with values where the
key matches the suffix or prefix.

For example, to set \*(T<levels\*(T> for
\*(T<osm_webmercator\*(T> and
\*(T<aerial_webmercator\*(T> and to set
\*(T<refresh_before\*(T> for
\*(T<osm_webmercator\*(T> and
\*(T<osm_utm32\*(T>:

.nf
\*(T<
seeds:
    ____webmercator:
        levels:
          from: 0
          to: 12

    osm____:
        refresh_before:
            days: 5
              \*(T>
.fi