aboutsummaryrefslogtreecommitdiff
blob: e86098831b46c30ac36fbedcc7d2c488ebb7b5f0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
<?xml version="1.0"?>
<guide self="general-concepts/mirrors/">
<chapter>
<title>Mirrors</title>

<section>
<title>Automatic Mirroring</title>

<body>
<p>
Packages will automatically have their <c>SRC_URI</c> components mirrored onto
Gentoo mirrors.  When fetching, Portage checks Gentoo mirrors first before
trying the original upstream location.
</p>

<p>
This is generally desired behaviour <d/> upstream mirrors are prone to being
rearranged, tidied out or having files modified.
</p>
</body>

<subsection>
<title>Restricting Automatic Mirroring</title>
<body>
<p>
Three <c>RESTRICT</c> keywords can be used to control the mirroring process.
</p>

<p>
The <c>RESTRICT=&quot;mirror&quot;</c> setting should be used if we cannot legally mirror
certain files; files will still be downloaded from the original locations.
</p>

<p>
The <c>RESTRICT="primaryuri"</c> setting causes Portage to try
original locations <e>first</e>, and then fall back to mirrors if necessary <d/> this
is sometimes useful if approximate download counts are needed, or if upstream
have a reliable mirror setup.
</p>

<p>
There is also <c>RESTRICT="fetch"</c>, which prevents Portage from trying to
fetch anything manually. The <uri link="::ebuild-writing/functions/pkg_nofetch">
pkg_nofetch</uri> function will be called if any <c>SRC_URI</c> components cannot be
found. This should only be used if a license requires it.
</p>
</body>
</subsection>

<subsection>
<title>Replacing Automatically Mirrored Files</title>
<body>
<p>
On rare occasions you may need to replace a file that is already mirrored.  In this case proceed as
follows:
<ol>
  <li>Put a copy of the new distfile on dev.gentoo.org into /space/distfiles-local</li>
  <li>commit the new manifest to CVS</li>
  <li>wait</li>
</ol>
After a few hours a cron job on dev.gentoo.org will fetch the file and replace the version on the
mirrors.  The file will be automatically removed from /space/distfiles-local after approximately two
weeks.
</p>

<p>
More general information about the internals of mirroring can be found on <uri
link="https://www.gentoo.org/proj/en/infrastructure/mirrors/overview-distfile.xml">infrastructure's
pages</uri>.
</p>
</body>
</subsection>


<subsection>
<title>Suitable Download Hosts</title>
<body>
<p>
If you have to host a source file (patch or tarball) yourself, as long as it is suitable to be
distributed by Gentoo Foundation (by license and legality), you're suggested to use your developer's
space at <c>dev.gentoo.org</c>. Since external overlays may depend on your patches/tarballs, using the
dev space at <c>dev.gentoo.org</c> keeps the distfiles at a stable and reliable infrastructure. If you
retire, other developers can take over your distfiles and place them into their own devspace.
</p>

<p>
Previous policy was to use <c>mirror://gentoo</c> directly, but this is now deprecated, as that
wouldn't allow to have long-term availability and traceability of the source files, which might be a
requirement of the license.
</p>

<p>
When you upload the file to <c>dev.gentoo.org:~/public_html</c>, you must ensure that it, and its
parent directories, are world-readable.
</p>
</body>
</subsection>
</section>

<section>
<title>Gentoo Mirrors</title>

<body>
<p>
To manually upload a file to <c>mirror://gentoo</c>, <c>scp</c> it to
<c>dev.gentoo.org:/space/distfiles-local</c>. You must ensure that the permissions
are set to <c>ug+rw</c> manually. The file should appear on the mirrors within four
hours (note that this is <e>less frequent</e> than
<uri link="::general-concepts/git-to-rsync"/>).

If the upstream download location for a package uses a non-standard TCP port
(anything other than 21, 80 or 443), you <e>must</e> manually mirror the files. Not
doing so can cause all kinds of problems with strict firewalls.
</p>
</body>
</section>

<section>
<title>Mirroring Process</title>

<body>
<figure short="Mirroring Process" link="diagram.png">
Diagram showing the mirroring process.
</figure>
</body>
</section>

</chapter>
</guide>